J2EE.6.2 Java 2 Platform, Standard Edition (J2SE) Requirements

J2EE.6.2.1 Programming Restrictions

The J2EE programming model splits the responsibilities between the application component providers and the J2EE product provider. As a result of this split, the application component providers focus on writing business logic and the J2EE product providers focus on providing a managed system infrastructure in which the application components can be deployed. This division of responsibilities requires that the application components do not contain functionality that would clash with the functions provided by the J2EE platform. If an application component tried to provide a function that the J2EE platform implements, the J2EE platform could not properly manage the function.

Thread management is one example of functionality that would clash with the J2EE platform's function. If enterprise beans were allowed to manage threads, the J2EE platform could not manage the life cycle of the enterprise beans, and it could not properly manage transactions.

This means that the application components must not use certain Java 2 Platform, Standard Edition (J2SE) functions. Because we do not want to subset the J2SE platform, and we want a J2SE product to be usable without modification by the J2EE product providers in the J2EE platform, we use the J2SE security permissions mechanism to express the programming restrictions imposed on application component providers. We specify the J2SE security permissions that the J2EE product provider must provide for the execution of each application component type. We call these permissions the J2EE security permissions set. The J2EE security permissions set is part of the J2EE API contract.

Since the exact set of security permissions in use in any installation is a matter of policy, this specification does not define a fixed set of permissions. Instead, the J2EE security permissions set defines the minimum set of permissions that application components should expect. Application components that need permissions not in this minimal set should describe their requirements in their documentation. (A future version of this specification will allow these security requirements to be specified in the deployment descriptor for application components.) All J2EE products must be capable of deploying application components that require the set of permissions described here. Some J2EE products will allow the set of permissions available to a component to be configurable, providing some components with more or fewer permissions than those described here.

From the application component provider's perspective, the provider must ensure that the application components do not use functions that would conflict with the J2EE security permission set.

The J2SE security permissions are fully described in http://java.sun.com/products/jdk/1.2/docs/guide/security/permissions.html.

Table J2EE.6-2 lists the J2EE security permissions set. This is the typical set of permissions that components of each type should expect to have.

Table J2EE.6-2. J2EE Security Permissions Set

Security Permissions	Target	Action
Application Clients
java.awt.AWTPermission	accessClipboard
java.awt.AWTPermission	accessEventQueue
java.awt.AWTPermission	showWindowWithout WarningBanner
java.lang.RuntimePermission	exitVM
java.lang.RuntimePermission	loadLibrary
java.lang.RuntimePermission	queuePrintJob
java.net.SocketPermission	*	connect
java.net.SocketPermission	localhost:1024-	accept,listen
java.io.FilePermission	*	read, write
java.util.PropertyPermission	*	read
Applet Clients
java.net.SocketPermission	codebase	connect
java.util.PropertyPermission	limited	read
Servlets/JSPs
java.lang.RuntimePermission	loadLibrary
java.lang.RuntimePermission	queuePrintJob
java.net.SocketPermission	*	connect
java.io.FilePermission	*	read, write
java.util.PropertyPermission	*	read
EJB Components
java.lang.RuntimePermission	queuePrintJob
java.net.SocketPermission	*	connect
java.util.PropertyPermission	*	read

Note that an operating system that hosts a J2EE product may impose additional security restrictions of its own that must be taken into account. For instance, the user identity under which a servlet executes is not likely to have permission to read and write all files.

J2EE.6.2.2 Additional Requirements

J2EE.6.2.2.1 Networking

The J2SE platform includes a pluggable mechanism for supporting multiple URL protocols through the java.net.URLStreamHandler class and java.net.URLStreamHandlerFactory interface.

The following URL protocols must be supported:

• file: Only reading from a file URL need be supported, that is, the corresponding URLConnection object's getOutputStream method may fail with an UnknownServiceException . Of course, file access is restricted according to the permissions described above.

• http: Only version 1.0 of the HTTP protocol need be supported, although HTTP 1.1 is allowed. An http URL must support both input and output.

• https : SSL version 3.0 must be supported by https URL objects. Both input and output must be supported.

The J2SE platform also includes a mechanism for converting a URL's byte stream to an appropriate object, using the java.net.ContentHandler class and java.net.ContentHandlerFactory interface. A ContentHandler object converts from a MIME byte stream to an object. ContentHandler objects are typically accessed indirectly using the getContent method of URL and URLConnection .

When accessing data of the following MIME types using the getContent method, objects of the corresponding Java type listed in Table J2EE.6-3 must be returned.

Table J2EE.6-3. Java Type of Objects Returned When Using the getContent Method

MIME Type	Java Type
image/gif	java.awt.ImageProducer
image/jpeg	java.awt.ImageProducer

Many environments will use HTTP proxies rather than connecting directly to HTTP servers. If HTTP proxies are being used in the local environment, the HTTP support in the J2SE platform should be configured to use the proxy appropriately; application components must not be required to configure proxy support in order to use an http URL.

Most enterprise environments will include a firewall that limits access from the internal network (intranet) to the public Internet, and vice versa. While it is typical for access using the HTTP protocol to pass through such firewalls, perhaps by using proxy servers, it is not typical that general TCP/IP traffic, including RMI-JRMP, RMI-IIOP, etc., can pass through firewalls. This of course has implications on the use of various protocols to communicate between application components. This specification requires only that, where local policy allows, HTTP access through firewalls be possible. Some J2EE products may provide support for tunneling other communication through firewalls, perhaps using HTTP, but this is neither specified nor required.

J2EE.6.2.2.2 AWT

AWT provides the ability to read binary image data and convert it into a java.awt.image object, using the createImage methods in java.awt.Toolkit . The AWT Toolkit must support binary data in the GIF and JPEG formats.

J2EE.6.2.2.3 JDBC API

The JDBC API allows for access to a wide range of data storage systems. The J2SE platform does not require that a system meeting the Java Compatible quality standards provide a database that is accessible through the JDBC API. To allow for the development of portable applications, this specification does require that such a database be available and accessible from a J2EE product through the JDBC API. Such a database must be accessible from web components, enterprise beans, and application clients, but need not be accessible from applets. In addition, the driver for the database must meet the JDBC compatible requirements in the JDBC specification.

J2EE applications should not attempt to load JDBC drivers directly. Instead, they should use the technique recommended in the JDBC specification and perform a JNDI lookup to locate a DataSource object. The JNDI name of the DataSource object should be chosen as described in Section J2EE.5.4, "Resource Factory References." The J2EE platform must be able to supply a DataSource that does not require the application to supply any authentication information when obtaining a database connection. Of course, applications may also supply a user name and password explicitly when connecting to the database.

When a JDBC API connection is used in an enterprise bean, the transaction characteristics will typically be controlled by the container. The component should not attempt to change the transaction characteristics of the connection, commit the transaction, roll back the transaction, or set autocommit mode. Attempts to make changes that are incompatible with the current transaction context may result in a SQLException being thrown. The EJB specification contains the precise rules for enterprise beans.

Similar restrictions apply when a component creates a transaction using the JTA UserTransaction interface. The component should not attempt operations on the JDBC Connection object that would conflict with the transaction context.

Drivers supporting the JDBC API used in a J2EE environment must meet a number of additional requirements on their implementation of JDBC APIs, described below.

• Drivers are required to provide accurate and complete metadata through the Connection.getMetaData method. J2EE applications should examine the DatabaseMetaData object and adapt their behavior to the capabilities of the current database. How this information is used to create portable applications that are independent of the underlying database vendor and driver is beyond the scope of this specification; see the Java 2 Platform, Enterprise Edition Application Programming Model ^[1] for additional information.

  ^[1] Available at http://java.sun.com/j2ee/apm.

• Drivers must support stored procedures ( DatabaseMetaData.supportsStoredProcedures must return true ). The driver must also support the full JDBC API escape syntax for calling stored procedures with the following methods on the Statement , PreparedStatement , and CallableStatement classes:

  - executeUpdate

  - executeQuery

  Support for calling stored procedures using the method execute on the Statement , PreparedStatement , and CallableStatement interfaces is not required because some databases don't support returning more than a single ResultSet from a stored procedure.

• Drivers must support all of the CallableStatement methods that apply to SQL92 types, including the following:

  - getBigDecimal(int parameterIndex)

  - getBoolean

  - getByte

  - getBytes

  - getDate(int parameterIndex)

  - getDate(int parameterIndex, Calendar cal)

  - getDouble(int parameterIndex)

  - getFloat(int parameterIndex)

  - getInt

  - getLong

  - getObject(int parameterIndex)

  - getShort

  - getString

  - getTime(int parameterIndex)

  - getTime(int parameterIndex, Calendar cal)

  - getTimestamp(int parameterIndex)

  - getTimestamp(int parameterIndex, Calendar cal)

  - registerOutParameter(int parameterIndex, int sqlType)

  - registerOutParameter(int parameterIndex, int sqlType, int scale)

  - wasNull()

  Support for the new BLOB , CLOB , ARRAY , REF , STRUCT , and JAVA_OBJECT types is not required. All parameter types ( IN , OUT , and INOUT ) must be supported.

• Full support for PreparedStatements is required. This implies support for the following methods:

  - setAsciiStream

  - setBigDecimal

  - setBinaryStream(int parameterIndex, InputStream x, int length)

  - setBoolean

  - setByte

  - setBytes

  - setCharacterStream

  - setDate(int parameterIndex, Date x)

  - setDate(int parameterIndex, Date x, Calendar cal)

  - setDouble

  - setFloat

  - setInt

  - setLong

  - setNull

  - setObject(int parameterIndex, Object x)

  - setObject(int parameterIndex, Object x, int targetSqlType)

  - setObject(int parameterIndex, Object x, int targetSqlType, int scale)

  - setShort

  - setString

  - setTime(int parameterIndex, Time x)

  - setTime(int parameterIndex, Time x, Calendar cal)

  - setTimestamp(int parameterIndex, Timestamp x)

  - setTimestamp(int parameterIndex, Timestamp x, Calendar cal)

  Support for the new BLOB , CLOB , ARRAY , REF , STRUCT and JAVA_OBJECT types is not required. Support for the PreparedStatement method getMeta Data is not required. This method must throw an SQLException if it is not supported.

• Full support for batch updates is required. This implies support for the following methods on the Statement , PreparedStatement , and CallableStatement classes:

  - addBatch

  - clearBatch

  - executeBatch

  Drivers are free to implement these methods any way they choose (including a non- batching implementation) as long as the semantics are correct. The following amendment was added in the JDBC 2.1 core specification, beyond what was in the JDBC 2.0 specification, and defines additional compliant behavior.

The Statement method executeBatch returns an integer array containing one entry for each statement in the batch. The elements are ordered in the same order in which the statements were executed (which is the same as the order in which they were originally added to the batch). For successful execution, an element of the array may have the following values:

• If the value of an array element is greater than or equal to zero, then the command executed successfully and the value is an update count indicating the number of rows in the database that were effected by the command.

• A value of “2 indicating that a command executed successfully, but that the number of effected rows is unknown.

In the event that execution of an element of the batch fails, a driver may or may not continue processing the remaining elements of the batch. However, a driver must always provide the same behavior when used with a particular DBMS. For example, a driver cannot continue processing after a failure for one batch, and not continue processing for another batch.

If a driver stops processing after the first failure, the array returned by the BatchUpdateException method getUpdateCounts will always contain fewer elements than were in the batch. Since commands are executed in the same order that they are added to the batch, if the array contained N elements, this means that the first N commands in the batch were processed successfully when the executeBatch method was called.

When a driver continues processing in the presence of failures, the number of elements, N, in the array returned by the BatchUpdateException method getUp dateCounts is always equal to the number of elements in the batch. The following additional array value is returned when a BatchUpdateException is thrown and the driver continues processing after a failure:

• A value of “3 indicates that the command or element failed to execute successfully. This value is also returned for elements that could not be processed for some reason; such elements fail implicitly.

Drivers that do not continue processing after a failure never return “3 in an update count array. Drivers of this type simply return a status array containing an entry for each command that was processed successfully.

An application can distinguish a driver that continues processing after a failure from one that does not by examining the size of the array returned by the BatchUpdateException method getUpdateCounts . A driver that continues processing always returns an array containing one entry for each element in the batch. A driver that does not continue processing after a failure will always return an array in which the number of entries is less than the number of elements in the batch.

The array returned by the PreparedStatement method executeBatch contains an element for each set of parameters in the batch, similar to the case for State ment . Each element either contains an update count or the generic success indicator ( “2).

Error handling in the case of PreparedStatement objects is the same as error handling in the case of Statement objects.

Error handling for the CallableStatement method executeBatch is analogous to PreparedStatement .

Note

JDBC 3.0 will define symbolic constants for the negative array entry values described above. Metadata to allow the exact behavior of a driver to be determined is planned.

• A driver must provide full support for DatabaseMetaData and ResultSetMetaData . This implies that all of the methods in the DatabaseMetaData interface must be implemented and must behave as specified in the JDBC 1.0 and 2.0 specifications. None of the methods in DatabaseMetaData and ResultSetMetaData may throw an exception because they are not implemented.

• The JDBC API core specification requires that JDBC compliant drivers provide support for the SQL92, transitional level, DROP TABLE command, full support for the CASCADE and RESTRICT options is required. As many popular databases do not support DROP TABLE as specified in the SQL92 specification, the following clarification is required.

A JDBC 2.1 compliant driver is required to support the DROP TABLE command as specified by the SQL92, transitional level. However, support for the CAS CADE and RESTRICT options of DROP TABLE is optional. In addition, the behavior of DROP TABLE is implementation defined when there are views or integrity constraints defined that reference the table that is being dropped.

J2EE.6.2.2.4 Java IDL

JavaIDL allows applications to access any CORBA object, written in any language, using the standard IIOP protocol. The J2EE security restrictions typically prevent all application component types except application clients from creating and exporting a CORBA object, but all J2EE application component types can be clients of CORBA objects.

J2EE.6.2.2.5 RMI-JRMP

JRMP is the Java technology-specific remote method invocation (RMI) protocol. The J2EE security restrictions typically prevent all application component types except application clients from creating and exporting an RMI object, but all J2EE application component types can be clients of RMI objects.