Application Management One Pager

[

|(TableOfContentstitle='')]

1. Introduction

1.1. Project/Component Working Name:

Application management

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

Tim Quinn (timothy.quinn@sun.com) & Hong Zhang (hong.zhang@sun.com)

1.3. Date of This Document:

original - 06/26/08
rev. 1 - 7/28/08
rev. 2 - 7/30/08 - clarification of new

<application-config>

2. Project Summary

2.1. Project Description:

Limited post-deployment editing of web app configuration

2.2. Risks and Assumptions:

For web apps in particular, there are several points at which users can customize their configuration: using this new application management feature, using the default-web.xml file, and using context.xml support provided by the web container. Exposing the application management customization point through the GUI could give the incorrect impression that the values configured there would be the ones the web app would see when it started. But because there is no GUI access to either default-web.xml or context.xml, and because those are other sources of customization, we have withdrawn GUI access to the application management configuration. Possibly an update to the GUI, delivered via the update center, might expose all of these sources of customization and therefore give the user a complete and accurate picture of how each web app will start up.

Users will be able to use the CLI get and set commands to change and see the customized configuration information once it has been added to domain.xml. For prelude the CLI does not have the ability to create or remove web app customizations. So users can hand-edit domain.xml to record the first customization of it after its deployment. Thereafter the CLI set and get commands provide access to those customization.

We are still exploring how best to provide the ability to add and remove customizations using the CLI.

3. Problem Summary

3.1. Problem Area:

Users want to be able to fine-tune the configuration of web apps during
and after deployment. Examples: changing env-entry values and changing
context-param settings. A key point is to avoid forcing the user
to go back, edit the original descriptor, and then repackage and redeploy
the application. The effect is similar to what Tomcat users can
do by editing the context.xml file to override various settings from a web app's descriptor.

The customizations should survive redeployments of the application. Customizations will not survive an undeployment of the app followed by a subsequent deployment.

Although only web app customization is supported in prelude the overall approach and the infrastructure additions to support this feature are general and were designed to work for any type of module. The common infrastructure of GlassFish is unaware of the particular customizations that a container and its GUI plug-in expose. Based on the requirements and additional feedback we targeted the initial implementation in prelude to env-entries and context-params in web apps. In general, each team that develops a container would choose what items of application configuration make sense to expose and then implement that container and the container's GUI plug-in to work together.

3.2. Justification:

User requirements and competitive parity.

4. Technical Description:

4.1. Details:

For prelude, users can customize the values of environment entries and context parameters that are specified in a web app's deployment descriptor. Other containers may add similar support in future releases.

User Experience

Initially users will edit domain.xml to add or remove customizations for an application. Subsequently they can use the CLI set and get commands to access those customizations.

Design - Persistence for the customizations and access to them

Each app's customizations are stored as subelements under the existing

<application>

<application>

<web-module-config>

<env-entry>

<context-param>

<env-entry>

<context-param>

For example, here is what a fragment of domain.xml might look like after a user had customized an app's configuration:

<application ...>
   <web-module-config>
      <env-entry>
         <env-entry-name>SomeName</env-entry-name>
         <env-entry-type>java.lang.Integer</env-entry-type>
         <env-entry-value>7</env-entry-value>
      </env-entry>
      ...
      <context-param>
         <param-name>greeting</param-name>
         <param-value>Hello</param-value>
      </context-param>
      ...
  </web-module-config>
</application>

Further, the user can suppress the effect of a context-param or an env-entry that might be present in the descriptor by specifying the attribute

ignoreDescriptorItem="true"

<context-param ignoreDescriptorItem="true">
      <param-name>greeting</param-name>
   </context-param>
   ...
   <env-entry ignoreDescriptorItem="true">
      <env-entry-name>Name2</env-entry-name>
   </env-entry>

Because the app customizations are stored in domain.xml user-written management clients can use AMX to retrieve and modify the customizations.

Design - Runtime

During app start-up the container reads both the app's deployment descriptor and, from the current configuration (loaded at start-up from domain.xml), the customized app config information (if the app has been previously deployed). The container combines the descriptor and the customizations to prepare the runtime environment for the app:

• The value from a customized

  <context-param>

  item overrides the corresponding value from the descriptor. The value, type, and description from a customized

  <env-entry>

  item override the corresponding settings from the descriptor.
• If the customized config omits a context-param or an env-entry that is present in the descriptor then the web container sets up that item in the runtime environment for the app as the descriptor specifies.
• If the customized config contains an item with no counterpart in the descriptor, then the container does set up that item for the app.
• If the customized config contains an item with the ignoreDescriptorItem attribute then the container will ignore the corresponding item, if present, from the descriptor.

Note that nothing is added to, removed from, or changed in the descriptor itself. Also,

Design - @Configured interfaces

The new module web/gui-plugin-common includes the classes that would be used by both the GUI plug-in and the container: the additional @Configured interfaces which extend ConfigBeanProxy.

The new interface ApplicationConfig is added to admin/config-api. This interface is the "abstract superinterface" for all container-specific interfaces that actually record customizations for their respective module types.

The existing Application interface is expanded to give access to its child ApplicationConfig items, taking advantage of the hk2 configuration framework feature that allows the actual children of Application which are of type ApplicationConfig to be any interface that extends ApplicationConfig:

@Configured
public interface Application ... {
...
    @Element("*")
    public List<ApplicationConfig> getApplicationConfig();
}

In the new web/webgui-plugin-common module resides

@Configured
public interface WebModuleConfig extends ApplicationConfig ... {
...
   @Element
   public List<EnvEntry> getEnvEntry();

   @Element
   public List<ContextParam> getContextparam();
...
}

In the future other containers can define their own subinterfaces of ApplicationConfig, tailored to their own customization needs, and package them in their own container-specific modules.

Note that domain.xml will never contain any elements like

<application-config>

<web-module-config>

<application>

Design - Multiple container types per application

More than one sniffer (and the associated deployer and container) can handle a given application. For example, web apps are handled by the web sniffer and also the security sniffer. The infrastructure changes for application management allow for all containers that handle an application to record and retrieve customizations related to that container type. The Application interface provides a method for retrieving ApplicationConfig objects of a certain requested type, so
a container can select only the customization items relevant to that type of container. Because a container team builds both the container and the sniffer (and the GUI plug-in for the container type) they all know what container type the sniffer will report and therefore what value to use in retrieving the correct customizations.

4.2. Bug/RFE Number(s):

4105

4.3. In Scope:

User can edit custom config for web app env-entry values and context-param value once the web app has been deployed.

The customizations survive redeployment.

4.4. Out of Scope:

Editing the config during deployment. Initially, the application management feature will require the app to be deployed before config editing is possible. To do otherwise might require the GUI to open the app being deployed to gain access to the descriptor. Currently the GUI does not need to read the archive as part of deploying it.

Maintaining customizations across an undeployment followed by a later deployment of the same app.

Container-specific commands to provide convenient CLI access to the customized application config.

GUI access to add, remove, and change customizations.

4.5. Interfaces:

4.5.1 Exported Interfaces

• Interface: AMX
• Stability: committed
• Former Stability (if changing):
• Comments: Addition of methods to get and set the custom config data

• Interface: CLI
• Stability: committed
• Former Stability (if changing):
• Comments: The get and set commands will provide access to the custom config data from the CLI.

4.5.2 Imported interfaces

n/a

4.5.3 Other interfaces (Optional)

Any private interfaces that may be of interest?

• Interface: domain.xml
• Stability: volatile
• Exporting Project: GlassFish v3
• Comments: This internal interface - the domain.xml format - is

strictly speaking internal but is widely used in practice. See admin/config impact below.

4.6. Doc Impact:

Deployment guide; admin reference

4.7. Admin/Config Impact:

No impact to admin of the product itself. So that application-level custom config can survive redeployments the server will store the custom config information in domain.xml as explained in the technical description.

4.8. HA Impact:

none

4.9. I18N/L10N Impact:

The user interface will need to display localizable labels for the
customizable config for web apps.

4.10. Packaging & Delivery:

No new modules.

4.11. Security Impact:

no changes

4.12. Compatibility Impact

Additions to AMX, GUI.
(w/ thanks to Lloyd for the input) The AMX ApplicationConfig will gain methods to get and set the children.

AMX will gain a new ApplicationConfigConfig interface to provide access to the ApplicationConfig information.

The AMX ApplicationConfig will gain methods to create a new ApplicationConfigConfig and return a Map of the existing ones.

The additions to domain.xml and AMX are backward-compatible. Additions to domain.xml are optional elements, not required ones.

No affect on migration or upgrade tools.

4.13. Dependencies:

none

5. Reference Documents:

n/a

6. Schedule:

6.1. Projected Availability:

The fall '08 release of v3 Prelude.