Difference between revisions of "Configuration Components"

From GCube System
Jump to: navigation, search
(→‎The JNDI Configuration)
(→‎The JNDI Configuration)
Line 40: Line 40:
 
== The JNDI Configuration ==
 
== The JNDI Configuration ==
  
−
In gCF, developers configure their code by avoiding to create some of the objects they need. Rather, they lookup the objects by name so that they can bind the same name to different objects without changing the code that uses them. At any point in time, the configuration of the code is thus a separately specified collections of name-object bindings. We discuss [[Contexts#Common Facilities|later]] how gCF supports object lookup, but we notice here that it builds upon an implementation of the [http://java.sun.com/products/jndi/ JNDI] interface. This explains why we speak of ''JNDI configuration'' and why the configuration file that contains all the name-object bindings is called <code>deploy-jndi-config.xml</code>.
+
In gCF, developers configure their code by avoiding to create some of the objects they need. Rather, they lookup those objects from a configuration file called <code>deploy-jndi-config.xml</code> where the bindings between names and objects are defined. This allows them to bind the same name to different objects at different times, without changing the code that uses them. We discuss [[Contexts#Common Facilities|later]] how gCF supports object lookup, but we notice here that it builds upon a local implementation of the [http://java.sun.com/products/jndi/ JNDI] interface for naming services, hence the name of the configuration file and our speaking of the ''JNDI configuration'' of the service.
  
−
The syntax for authoring the JNDI configuration is based on XML, and its [http://www.globus.org/toolkit/docs/4.0/common/javawscore/developer-index.html#s-javawscore-developer-JNDIDetails definition] is lifted from lower-level technologies. There are essentially two types of bindings:
+
The syntax of the JNDI configuration file is based on XML, and its [http://www.globus.org/toolkit/docs/4.0/common/javawscore/developer-index.html#s-javawscore-developer-JNDIDetails definition] is lifted from lower-level technologies. We can summarise it as follows:
  
−
*'''environments''': these are bindings of names to values of a set of pre-defined classes, such as <code>Integer</code> and <code>String</code>.
+
* object bindings are contained into <code>service</code> elements and <code>service</code> elements have a <code>name</code> attribute and are contained in a <code>jndiConfig</code> root element.
−
:An environment is an empty element named <code>environment</code> with <code>name</code> and <code>type</code> attributes. The <code>name</code> attribute names the bound value and the <code>type</code> attributes gives the fully qualified name of its class.
+
 
 +
<pre>
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<jndiConfig xmlns="http://wsrf.globus.org/jndi/config">
 +
 
 +
 
 +
<service name="...">
 +
 
 +
            ...bindings...
 +
 +
</service>
 +
 +
<service name="...">
 +
 +
              ....bindings...
 +
 +
</service>
 +
 
 +
<service name="...">
 +
               
 +
                ...bindings...
 +
 +
</service>
 +
 
 +
</jndiConfig>
 +
</pre>
 +
 
 +
*a <code>service</code> element identifies a ''section'' of the service configuration dedicated to a single port-type. The only exception is one for one distinguished section, the ''global section'', that is used to collect cross port-type bindings and is thus associated with the service as a whole.
 +
 
 +
*the <code>name</code> of configuration sections must be unique across all services deployed on the gHN and, since we cannot tell in advance what services will be codeployed with any given one, it must be globally unique. For port-type sections, the name must match the name of the port-type in the [[#The Deployment Descriptor|deployment descriptor]]. For the global section the convention the naming convention is to rely on the namespace of the service implementation. In particular, the global section can be named after the main package of the service implementation, i.e. the first package that ensures uniqueness of naming to all the implementation components
 +
 
 +
 
 +
<pre>
 +
<?xml version="1.0" encoding="UTF-8"?>
 +
<jndiConfig xmlns="http://wsrf.globus.org/jndi/config">
 +
 
 +
        <!--global section -->
 +
<service name="/org/acme/sample">
 +
 
 +
            ...bindings...
 +
 +
</service>
 +
 +
        <!-- port-type section -->
 +
<service name="org/acme/sample/porttypeone">
 +
 +
              ....bindings...
 +
 +
</service>
 +
 
 +
        <!-- port-type section -->
 +
<service name="org/acme/sample/porttypetwo">
 +
               
 +
                ...bindings...
 +
 +
</service>
 +
 
 +
</jndiConfig>
 +
</pre>
 +
 
 +
 
 +
* there are essentially two types of bindings:
 +
 
 +
**'''environments''': these are bindings of names to values of a set of pre-defined classes, such as <code>Integer</code> and <code>String</code>.
 +
::An environment is an empty element named <code>environment</code> with <code>name</code> and <code>type</code> attributes. The <code>name</code> attribute names the bound value and the <code>type</code> attributes gives the fully qualified name of its class.
  
 
<pre>
 
<pre>
Line 51: Line 115:
 
</pre>   
 
</pre>   
  
−
*'''resources''': these are bindings of names to to values of custom classes.
+
**'''resources''': these are bindings of names to to values of custom classes.
−
: A resource is a complex element named <code>resource</code> and with <code>name</code> and <code>type</code> attributes, and a single <code>resourceParams</code> child element. The attributes retain the semantics they have in environments, except that <code>type</code> can identify any class in principle. The <code>resourceParams</code> elements contains in turn one ore more <code>parameter</code> elements, where each <code>parameter</code> contains a <code>name</code> element and a <code>value</code> element. One of the parameters ''must'' have a name of <code>factory</code>, and its value ''must'' be the qualified name of a class capable to generate a value of the resource's <code>type</code> and to initialise it with the values of the remaining parameters (as <code>String</code>s).  
+
:: A resource is a complex element named <code>resource</code> and with <code>name</code> and <code>type</code> attributes, and a single <code>resourceParams</code> child element. The attributes retain the semantics they have in environments, except that <code>type</code> can identify any class in principle. The <code>resourceParams</code> elements contains in turn one ore more <code>parameter</code> elements, where each <code>parameter</code> contains a <code>name</code> element and a <code>value</code> element. One of the parameters ''must'' have a name of <code>factory</code>, and its value ''must'' be the qualified name of a class capable to generate a value of the resource's <code>type</code> and to initialise it with the values of the remaining parameters (as <code>String</code>s).  
  
 
<pre>
 
<pre>
Line 70: Line 134:
  
 
All the pre-defined resources use the <code>globus.wsrf.jndi.BeanFactory</code> factory class. This is a generic factory that can instantiate any class that defines setter methods that match all the other resource parameters (e.g. <code>setBar(String)</code>). Developers can defined their own factories, though the <code>BeanFactory</code> is expected to satisfy most resource configuration requirements.
 
All the pre-defined resources use the <code>globus.wsrf.jndi.BeanFactory</code> factory class. This is a generic factory that can instantiate any class that defines setter methods that match all the other resource parameters (e.g. <code>setBar(String)</code>). Developers can defined their own factories, though the <code>BeanFactory</code> is expected to satisfy most resource configuration requirements.
−
 
−
Environments and resources must be collected into <code>service</elements>, where a <code>service</code> has a <code>name</code> attribute that identifies the scope in which the environments and resources are valid. In particular, <code>service</code> elements identify ''sections'' of the JNDI configurations dedicated to the configuration of individual service port-types and must be named in acccordance with the [[#The Deployment Descriptor|deployment descriptor]]. The only exception is for one distinguished section, the ''global section'', that is used to collect cross port-type bindings. The naming convention here is to rely on the namespace of the service implementation; in particular, the global section can be named after the main package of the service implementation, i.e. the first package that ensures uniqueness of naming to all the implementation components.
 
−
 
−
<pre>
 
−
 
−
<!-- global section -->
 
−
<service name="org/acme/sample">
 
−
...
 
−
</service>
 
−
 
−
 
−
<service name="org/acme/porttype1">
 
−
...
 
−
</service>
 
−
 
−
 
−
<service name="org/acme/porttype3">
 
−
...
 
−
</service>
 
−
 
−
</pre>
 
  
 
== The Deployment Descriptor ==
 
== The Deployment Descriptor ==
  
 
[in progress]
 
[in progress]

Revision as of 21:02, 27 April 2009

Developing a gCube service is far more than writing code. Developers are expected to produce a number of files to configure the service and to describe it from a variety of perspectives and for a variety of purposes. For uniformity, we think of these non-programmatic components of the service implementation as the configuration of the service.

Overview

What does needs configuration, and what for?

  • the service as a whole, so that it can be correctly managed by the infrastructure.
This is a public form of configuration that identifies the service, its requirements, its dependencies, and its implementation components. The result is the profile of the service, a configuration requirement that services share with all the other types of gCube resources.
  • the interface of the service, so that the service can be correctly used by clients.
This is a public form of configuration that describes the operations that can be invoked on the service and how to invoke them. The result is a number of interface definitions, one for each port-type of the service.
  • the security requirements of the service, so that the service can be safely used by clients.
This is a public form of configuration that describes the authentication and authorisation requirements of the service. The result is the security descriptor' of the service.
  • the actual implementation of the service, so that the service will exhibit the required runtime behaviour.
This is the primary form of local configuration that describes all the choices that were not or could not be made in the code. The result is the JNDI configuration' of the service.
  • the process used to build the service, so that the service can be packaged correctly for deployment.
This is a local form of configuration that customises the process that yields the software artifact required for deployment. The result is the build configuration of the service. The build configuration is not part of the service implementation, and thus it is not included in the very artifact it helps to produce. While gCF makes no assumption on the build process, gCore supports a particular build approach and requires a particular configuration file for it. We illustrate these requirements in the Primer, and do not discusse them further in this Guide.
  • the process used to deploy the service, so that the service can be correctly managed by the gHN.
This is a local form of configuration that provides the information required by the gHN to activate the service and dispatch client calls to it. The result is the deployment descriptor of the service.

Profile, WSDL definitions, security decriptors, JNDI configuration, and deployment descriptor are all part of the software artifact that is deployed on a gHN. After service deployment, its configuration components are collected in a service-specific directory under $GLOBUS_LOCATION/etc. We call this directory the configuration directory of the service.

The Service Profile

The service profile is contained in a file called profile.xml and is governed by the XML Schema in $GLOBUS_LOCATION/share/schema/gcube/common/core/profiles/service.xsd.

[in progress]

Interface Definitions

[in progress]

The Security Descriptor

[in progress]

The JNDI Configuration

In gCF, developers configure their code by avoiding to create some of the objects they need. Rather, they lookup those objects from a configuration file called deploy-jndi-config.xml where the bindings between names and objects are defined. This allows them to bind the same name to different objects at different times, without changing the code that uses them. We discuss later how gCF supports object lookup, but we notice here that it builds upon a local implementation of the JNDI interface for naming services, hence the name of the configuration file and our speaking of the JNDI configuration of the service.

The syntax of the JNDI configuration file is based on XML, and its definition is lifted from lower-level technologies. We can summarise it as follows:

  • object bindings are contained into service elements and service elements have a name attribute and are contained in a jndiConfig root element. 
<?xml version="1.0" encoding="UTF-8"?>
<jndiConfig xmlns="http://wsrf.globus.org/jndi/config">


 	<service name="...">

            ...bindings...
		 	
	</service>
	
 	<service name="...">
	
               ....bindings...
	
	</service>

 	<service name="...">
                
                ...bindings...
	 	
	</service>
  
</jndiConfig>
  • a service element identifies a section of the service configuration dedicated to a single port-type. The only exception is one for one distinguished section, the global section, that is used to collect cross port-type bindings and is thus associated with the service as a whole.
  • the name of configuration sections must be unique across all services deployed on the gHN and, since we cannot tell in advance what services will be codeployed with any given one, it must be globally unique. For port-type sections, the name must match the name of the port-type in the deployment descriptor. For the global section the convention the naming convention is to rely on the namespace of the service implementation. In particular, the global section can be named after the main package of the service implementation, i.e. the first package that ensures uniqueness of naming to all the implementation components


<?xml version="1.0" encoding="UTF-8"?>
<jndiConfig xmlns="http://wsrf.globus.org/jndi/config">

        <!--global section --> 
 	<service name="/org/acme/sample">

            ...bindings...
		 	
	</service>
	
        <!-- port-type section -->
 	<service name="org/acme/sample/porttypeone">
	
               ....bindings...
	
	</service>

        <!-- port-type section -->
 	<service name="org/acme/sample/porttypetwo">
                
                ...bindings...
	 	
	</service>
  
</jndiConfig>


  • there are essentially two types of bindings:
    • environments: these are bindings of names to values of a set of pre-defined classes, such as Integer and String.
An environment is an empty element named environment with name and type attributes. The name attribute names the bound value and the type attributes gives the fully qualified name of its class.
<environment name="foo" value="bar" type="java.lang.String" />
    • resources: these are bindings of names to to values of custom classes.
A resource is a complex element named resource and with name and type attributes, and a single resourceParams child element. The attributes retain the semantics they have in environments, except that type can identify any class in principle. The resourceParams elements contains in turn one ore more parameter elements, where each parameter contains a name element and a value element. One of the parameters must have a name of factory, and its value must be the qualified name of a class capable to generate a value of the resource's type and to initialise it with the values of the remaining parameters (as Strings). 
<resource name="foo" type="org.acme.Foo">
  <resourceParams>	
    <parameter>
       <name>factory</name>
          <value>org.acme.FooFactory</value>
    </parameter>
    <parameter>
         <name>bar</name>
         <value>baz</value>
    </parameter>               
 </resourceParams>
</resource>

All the pre-defined resources use the globus.wsrf.jndi.BeanFactory factory class. This is a generic factory that can instantiate any class that defines setter methods that match all the other resource parameters (e.g. setBar(String)). Developers can defined their own factories, though the BeanFactory is expected to satisfy most resource configuration requirements.

The Deployment Descriptor

[in progress]

Retrieved from "https://gcore.wiki.gcube-system.org/index.php?title=Configuration_Components&oldid=1250"