GlassFish - World's first Java EE 7 Application Server


1. Services Metadata Schema

Here is the initial proposed schema for services metadata:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<xs:schema version="1.0" xmlns:xs="http://www.w3.org/2001/XMLSchema">

  <xs:element name="glassfish-services" type="serviceMetadata"/>

  <xs:complexType name="property">
    <xs:sequence/>
    <xs:attribute name="name" type="xs:string"/>
    <xs:attribute name="value" type="xs:string"/>
  </xs:complexType>

  <xs:complexType name="serviceCharacteristics">
      <xs:annotation>
          <xs:documentation>
              The characteristics element defines the characteristics
              using which an appropriate IMS template should be chosen for
              creating the service.
          </xs:documentation>
      </xs:annotation>
    <xs:sequence>
      <xs:element name="characteristic" type="property" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="serviceDescription">
      <xs:annotation>
          <xs:documentation>
              The service-description element defines high level requirement
              on how the services should be provisioned and configured.
          </xs:documentation>
      </xs:annotation>
    <xs:sequence>
      <xs:choice minOccurs="0">
        <xs:element name="template" type="templateIdentifier"/>
        <xs:element name="characteristics" type="serviceCharacteristics"/>
      </xs:choice>
      <xs:element name="configurations" minOccurs="0">
          <xs:annotation>
              <xs:documentation>
                  The configurations element defines how the service should be
                  configured. For example, number of nodes in a multi-node service.
              </xs:documentation>
          </xs:annotation>
        <xs:complexType>
          <xs:sequence>
            <xs:element name="configuration" type="property" minOccurs="0" maxOccurs="unbounded"/>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
    <xs:attribute name="init-type" type="xs:string"/>
    <xs:attribute name="name" type="xs:string" use="required">
        <xs:annotation>
            <xs:documentation>
                The name of the service should be unique in the PaaS runtime.
            </xs:documentation>
        </xs:annotation>
    </xs:attribute>
  </xs:complexType>

  <xs:complexType name="templateIdentifier">
      <xs:annotation>
          <xs:documentation>
              The template element specifies the identifier of the IMS template
              that should be chosen to create the service.
          </xs:documentation>
      </xs:annotation>
    <xs:sequence/>
    <xs:attribute name="id" type="xs:string" use="required"/>
  </xs:complexType>

  <xs:complexType name="serviceMetadata">
      <xs:annotation>
          <xs:documentation>
              The glassfish-services is a root element of a Service Metadata
              deployment descriptor. Holds both service description and
              service references.
          </xs:documentation>
      </xs:annotation>
    <xs:sequence>
      <xs:element name="service-description" type="serviceDescription" minOccurs="0" maxOccurs="unbounded"/>
      <xs:element name="service-reference" type="serviceReference" minOccurs="0" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="serviceReference">
      <xs:annotation>
          <xs:documentation>
              The service-reference element defines how the services should be
              associated/wired with each other.
          </xs:documentation>
      </xs:annotation>
    <xs:sequence>
      <xs:element name="properties">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="entry" minOccurs="0" maxOccurs="unbounded">
              <xs:complexType>
                <xs:sequence>
                  <xs:element name="key" minOccurs="0" type="xs:anyType"/>
                  <xs:element name="value" minOccurs="0" type="xs:anyType"/>
                </xs:sequence>
              </xs:complexType>
            </xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
    <xs:attribute name="name" type="xs:string" use="required"/>
    <xs:attribute name="optional" type="xs:boolean" use="required"/>
    <xs:attribute name="service-name" type="xs:string" use="required"/>
    <xs:attribute name="type" type="xs:string"/>
  </xs:complexType>
</xs:schema>

2. Some Scenarios:

2.1. An external JDBC service is available. But that service was not configured using 'create-external-service' command. However, the application wants to use it.

In this case, specify the raw information in <jdbc-connection-pool> properties. This scenario is already supported in current version of GlassFish.

2.2. Referencing to external service which was already configured using 'create-external-service' command.

For JDBC case, 'create-external-service' command had already created a shared jdbc connection pool. The name of the shared connection pool is known to the user (say shared-jdbc-pool-A)

Case (a). The application will directly use the shared connection pool using the current mechanism, like this:

glassfish-resources.xml :->
--------------------------------

<jdbc-resource jndi-name="jdbc/myres" pool-name="shared-jdbc-pool-A"/>

Case (b). The application does not want to use the shared connection pool created by 'create-external-service' . Instead it wants to create its own connection pool around the externally created service (say external-service-A):

glassfish-resources.xml :->
-------------------------------

<jdbc-connection-pool datasource-classname="com.mysql.jdbc.Driver" res-type="javax.sql.XADataSource" name="myPoolB">
      <property name="serviceName" value="external-service-A"/>
      <property name="User" value="dbuser" />
      <property name="Password" value="dbpassword" />
      <property name="driverType" value="4" />
      <property name="dataBaseName" value="testdb" />
      <property name="createDatabaseIfNotExist" value="true" />
      <property name="server.basedir" value="/tmp/testDB" />
</jdbc-connection-pool>

<jdbc-resource jndi-name="jdbc/myres2" pool-name="myPoolB"/>

[external-service-A would know the actual host, port, admin credentials of the external database server]

JMS is also similar to JDBC case wherein the connector-connection-pool will have

<property name="serviceName" value="external-jms-service-A"/

2.3 Referencing a shared provisioned service which was created using 'create-shared-service' command:

Same as 2.2, except that the service-name would point to the name of the shared service to bind to.

2.4. The JMS service needs to be provisioned during deployment of the application (specification through templates):

glassfish-services.xml :->
------------------------------

<?xml version="1.0" encoding="UTF-8"?>

<glassfish-services>

    <!-- Description on how to provision the service -->
    <service-description name="myMQ" init-type="lazy">
        <template id="OpenMQ_MINI"/> <!-- name of the template to be used to provision myMQ service -->
        <configurations> <!-- provisioned service needs to have the following configurations -->
            <configuration name="JVM_OPTIONS" value="-Xmx1024m"/> <!-- set the heap size of MQ broker service to 1GB -->
        </configurations>
    </service-description>

</glassfish-services>

glassfish-resources.xml :->
--------------------------------
<connector-connection-pool associate-with-thread="false" connection-creation-retry-attempts="0" connection-creation-retry-interval-in-seconds="10" connection-definition-name="javax.jms.ConnectionFactory" connection-leak-reclaim="false" connection-leak-timeout-in-seconds="0" fail-all-connections="false" idle-timeout-in-seconds="300" is-connection-validation-required="false" lazy-connection-association="false" lazy-connection-enlistment="false" match-connections="true" max-connection-usage-count="0" max-pool-size="32" max-wait-time-in-millis="60000" name="jms/JupiterConnectionFactory" pool-resize-quantity="2" resource-adapter-name="jmsra" steady-pool-size="8" validate-atmost-once-period-in-seconds="0">

<!--
  <property name="Password" value="guest" />
  <property name="UserName" value="guest" />
  <property name="AddressList" value="Host1,Host2:12148" />
-->
<property name="ServiceName" value="myMQ" />
<property name="IMQ_DESTINATION_NAME" value="MyTopic"/>
  </connector-connection-pool>

2.5. The JMS service needs to be provisioned during deployment of the application (specification through characteristics):

glassfish-services.xml :->
------------------------------

<?xml version="1.0" encoding="UTF-8"?>

<glassfish-services>

    <!-- Description on how to provision the service -->
    <service-description name="myMQ" init-type="lazy">
        <!-- Based on the characteristics specified below, the Orchestrator
would match to a Template in the Template Catalog and provision that Service -->
        <characteristics>
           <characteristic name="service-type" value="JMS"/>
           <characteristic name="product-vendor" value="Oracle"/>
           <characteristic name="product-name" value="OpenMQ"/>
           <characteristic name="product-version" value="4.6"/>
           <characteristic name="os-name" value="Linux"/>
        </characteristics>

        <configurations> <!-- provisioned service needs to have the following configurations -->
            <configuration name="JVM_OPTIONS" value="-Xmx1024m"/> <!-- set the heap size of MQ broker service to 1GB -->
        </configurations>
    </service-description>

</glassfish-services>

glassfish-resources.xml is same as in 2.4

2.5 Provisioning of application-scoped GlassFish service:

glassfish-services.xml :->
------------------------------

<?xml version="1.0" encoding="UTF-8"?>

<glassfish-services>

<service-description name="myGlassFish" init-type="lazy">

        <characteristics>
           <characteristic name="service-type" value="JavaEE"/>
           <characteristic name="product-vendor" value="Oracle"/>
           <characteristic name="product-name" value="GlassFish"/>
           <characteristic name="product-version" value="3.2"/>
           <characteristic name="os-name" value="Linux"/>
        </characteristics>

        <configurations> <!-- provisioned service needs to have the following configurations -->
            <configuration name="JVM_OPTIONS" value="-Xmx1024m"/>
            <configuration name="min.clustersize" value="2"/>
            <configuration name="max.clustersize" value="5"/>
            <configuration name="pre.deploy.script" value="file:///tmp/create_resources.asadmin"/>
        </configurations>

</service-description>

</glassfish-services>

Comments:

The schema documented by the August 12, 2011 version of this page (http://wikis.sun.com/pages/viewpage.action?pageId=241218039) is pretty weak.

While the extensive use of name/value pairs makes it easy to use as we prototype the feature, it makes it hard to:
*document what users can put in this file and
*create editors that provide useful code completion and the like

Please consider creating a schema that is 'richer'.
Posted by vince.kraemer at Aug 31, 2011 13:12