GrizzlyConfig One Pager

1. Introduction

1.1. Project/Component Working Name:

Grizzly Configuration

1.2. Name(s) and e-mail address of Document Author(s)/Supplier:

The individuals who contributed to this document are:

Name: Jeanfrancois.Arcand@Sun.COM, Oleksiy.Stashok@Sun.COM, Dhiru.Pandey@Sun.COM, Justin.Lee@Sun.com

1.3. Date of This Document:

06/30/08
12/08/08

2. Project Summary

2.1. Project Description:

Grizzly configuration specifies the schema of the element (or file in case of standalone) used by Grizzly to configure the network services (transport, protocol and listeners)

2.2. Risks and Assumptions:

2.2.1 Coordination is required with both the admin CLI and GUI teams which will complicate scheduling.

3. Problem Summary

3.1. Problem Area:

Previous versions of GlassFish application server handled HTML/HTTP requests from within the web container. Modular architecture of V3 requires that this behavior be changed so that these requests can now be handled by the barebone V3 nucleus even before any of the containers have been started. As a result, grizzly configuration which was earlier part of the web container configuration needs to be separated out into its own configuration element.

There may be situations where Grizzly may need to be configured in the absence of GlassFish. The configuration should be able to handle such scenarios as well.

In domain.xml System properties where widely used to tune the performance, so it was very difficult to have a different configuration for a different listeners.
Grizzly-config is less dependent on system properties and property elements. Most of the transport related properties from domain.xml, in grizzly-config become XML elements and attributes.

3.2. Justification:

This project provides the necessary infrastructural support for modularity - one of the main features of V3 release.
Additionally the configuration schema provides the necessary plug-in points for extensibility in terms of protocol handling.

4. Technical Description:

4.1. Details:

As stated above, Grizzly is now part of the nucleus of GlassFish V3. In earlier versions of GlassFish, Grizzly was configured via the http-service element of domain.xml to field the HTTP traffic. In V3, because of this change, HTTP traffic can be handled by the nucleus and so the configuration of Grizzly needs to be separated out to its own configuration element in domain.xml.

The schema for the Grizzly configuration is described here. The new network-config element would be added to config element of sun-domain.dtd as shown below:

<!ELEMENT config
    (network-config, http-service, iiop-service, admin-service, connector-service?,            
    web-container, ejb-container, mdb-container, jms-service?, log-service,    
    security-service, transaction-service, monitoring-service,                 
    diagnostic-service?, java-config, availability-service?, thread-pools,     
    alert-service?, group-management-service?, management-rules?,              
    system-property*, property*)>

Any network-specific configuration under <code>http-service</code> in <code>domain.xml</code> will be deprecated and mapped to the new <code>network-config</code> element. However, any HTTP protocol specific configuration will be retained under it. Additionally, Grizzly configuration done in earlier versions of GlassFish using the -D properties will also be deprecated. Backward compatibility in V3 runtime will be maintained to support these by intelligently creating the network-config runtime bean in the admin infrastructure that will read values from these deprecated elements (use defaults where required) and populate the new network-config runtime bean which is then used to bootstrap Grizzly.

The same schema will also be used to configure Grizzly in standalone mode i.e. in the absence of GlassFish. Currently, Grizzly in standalone mode is configured programmatically. The javadoc for the new grizzly classes are attached and should be considered the authoritative documentation. An example grizzly configuration file can be found here. Here is a migrated version of a v3 domain.xml that reflects the proposed changes.

The relevant changed portions are highlighted below:

<network-config>
   <transports>
       <transport name="http"/>
   </transports>
   <protocols>
       <protocol name="http">
           <http default-virtual-server="server" header-buffer-length-bytes="8192">
               <file-cache enabled="false"/>
           </http>
       </protocol>
       <protocol name="http-admin">
           <http default-virtual-server="__asadmin"/>
       </protocol>
       <protocol name="https" security-enabled="true">
           <ssl ssl3-enabled="false" cert-nickname="s1as"/>
       </protocol>
   </protocols>
   <network-listeners>
       <thread-pool thread-pool-id="http-threads" min-thread-pool-size="2" max-thread-pool-size="20"/>
       <network-listener name="http-listener-1" transport="http" protocol="http" address="0.0.0.0" port="8080"/>
       <network-listener name="http-listener-2" transport="http" protocol="https" address="0.0.0.0" port="8181"/>
       <network-listener name="admin-listener" transport="http" protocol="http-admin" address="0.0.0.0" port="4848"/>
   </network-listeners>
</network-config>
<http-service>
    <access-log rotation-interval-in-minutes="15" rotation-suffix="yyyy-MM-dd"/>
    <virtual-server id="server" network-listeners="http-listener-1,http-listener-2"/>
    <virtual-server id="__asadmin" network-listeners="admin-listener"/>
</http-service>

4.2. Bug/RFE Number(s):

4.3. In Scope:

Standalone Grizzly runtime would also use the same configuration schema to bootstrap.

4.4. Out of Scope:

4.5. Interfaces:

Refer to the javadoc for the configuration element specified above in section 4.1.

4.5.1 Exported Interfaces

Disclose all interfaces that this project exports.

• Interface: network-config element described in the javadoc
• Stability: Committed
• Former Stability (if changing):
• Comments:

4.5.2 Imported interfaces

None

4.5.3 Other interfaces (Optional)

None

4.6. Doc Impact:

Product manuals/guides will need to be modified to incorporate changes related to administering and using network (Grizzly) configuration

4.7. Admin/Config Impact:

Admin console and cli would need to support this new configuration schema.

4.8. HA Impact:

No impact.

4.9. I18N/L10N Impact:

I18N/L10N impact would be on the Admin Console/CLI used to configure this element

4.10. Packaging & Delivery:

In GlassFish V3, this will be an element in domain.xml and will be part of the V3 distribution. It will also be part of the standalone Grizzly distribution.

4.11. Security Impact:

For V3 Transport Level Security (TLS) for HTTP protocol would be configured using this. In earlier releases of GlassFish the same information was picked up from a various protocol listener elements which were part of the protocol service elements for e.g.
<http-listener> element specified in <http-service> element of domain.xml. To maintain backward compatibility, V3 runtime would also be able to use the TLS related configuration specified in the protocol listener elements which were part of the protocol service elements of the V2 domain.dtd.

4.12. Compatibility Impact

Any network-specific configuration under <code>http-service</code> in <code>domain.xml</code> will be deprecated and mapped to the new <code>network-config</code> element. However, any HTTP protocol specific configuration will be retained under it. Additionally, Grizzly configuration done in earlier versions of GlassFish using the -D properties will also be deprecated. Backward compatibility in V3 runtime will be maintained to support these by intelligently creating the network-config runtime bean in the admin infrastructure that will read values from these deprecated elements (use defaults where required) and populate the new network-config runtime bean which is then used to bootstrap Grizzly.

Below we propose migration map for http-service children elements and attributes. Where <code>http-service</code> elements or attributes have been mapped to corresponding <code>network-config</code> elements or attributes, respectively, their new dotted names are derived from the mappings. Items below marked as "not supported" are not currently used by the system and will be dropped during the migration. A warning will be logged in the process.

1) http-listener

2) http-protocol

3) http-service

4) request-processing

5) connection-pool

6) virtual-server

7) keep-alive

8) http-file-cache

9) thread-pool

10) The following properties will need to be intercepted and mapped accordingly. This will likely mean adding logic to catch these properties when using asadmin set-jvm-property and migrating existing instances in domain.xml to the appropriate xml element.
Note for v2 migrations: if you are using GlassFish v3, all properties start with com.sun.enterprise.web.connector.grizzly instead of com.sun.grizzly

The following table lists properties currently being processed under the <http-listener> element that will be remapped:

The following table lists properties currently being processed under the <virtual-server> element that will be promoted to attributes on the elements rather than properties:

Glassfish admin commands.

1) Update existing commands.

2) Add following commands:

GUI Updates

1. Though a network-listener can have different transports defined, exposing that level of detail right now might be more detail than is useful. I'd recommend inferring a standard transport with default values. The admin gui would not change the transport reference, however, should a more advanced user manually edit domain.xml with custom transport definitions/configurations. Without port unification, exposing transports just for http usage seems a little overkill.
2. The HTTP Listener page can probably remain relatively unchanged. Some fields will need to be remapped to different properties, perhaps, but I don't see any conflicting values with the exception of acceptorThreads.

Migration

1. Migrate existing v2 domain.xml files to the new schema. Fold in grizzly properties to appropriate xml structures
2. dotted properties will need to be mapped. There are doubtless scripts out there setting using "asadmin set foo.bar=bob" these so we'll need to handle those appropriately. Do we handle set-jvm-property similarly? Try to align with work done for logging.

4.12.1 Open Issues

1. notes from migration/admin team (rebecca? kedar?)
   1. admin gui impact assessment
2. dotted property name mapping (kedar?)

4.13. Dependencies:

• Admin infrastructure
• Admin GUI
• CLI

5. Reference Documents:

Project Grizzly

6. Schedule:

6.1. Projected Availability: