JCA / Datasources in domain.xml

[jesper.pedersen]

We need to include support for datasource and resource adapter deployments in the domain.xml definition.

There are a couple of areas that should be supported:

• Deployment of a datasource
• Deployment of a resource adapter archive

Datasources

The best solution is to have a type safe definition of the resource adapter archives and datasources. This will provide the best tooling support and up-front validation.

Using the existing jboss-ds_6_0.dtd as a starting point and removing deprecated and unused elements we are looking at

<datasources xmlns="urn:jboss:datasources:1.0">
  <datasource jndi-name="java:/DefaultDS" pool-name="DefaultDS" enabled="true">
     <min-pool-size>1</min-pool-size>
     <max-pool-size>10</max-pool-size>
     <username>sa</username>
     <password>sa</password>
     <connection-url>jdbc:hsqldb:hsql://${jboss.bind.address}:1701</connection-url>
     <driver-class>org.hsqldb.jdbcDriver</driver-class>
     <type-mapping>Hypersonic SQL</type-mapping>
     <transaction-isolation>TRANSACTION_READ_COMMITTED</transaction-isolation>
     ...
  </datasource>

  <xa-datasource jndi-name="java:/PostgreSQLXADS" pool-name="PostgreSQLXADS" enabled="true">
     ...
  </xa-datasource>

</datasources>

(Full XSD to follow)

Also; we need to include the security elements in domain.xml as the datasources depends on the security-domain functionality. I'll ping Marcus about this thread.

Resource adapters

Ideally it would be best if a resource adapter archive could be deployed without having any additional metadata defined other than the archive itself.

However we need to define the JNDI binding per connection factory somehow - we will extend the jboss-ra.xml file to allow this of course. So a user should be able to define the mapping in domain.xml.

In addition keeping the functionality where a user can select the connection manager to use for the resource adapter with the fallback to the version specified by the transaction support property in ra.xml.

The ConnectionManager comes in three flavors

• NoTx
• LocalTx
• XATx

<connection-factories xmlns="urn:jboss:connection-factories:1.0">
   <no-tx-connection-factory jndi-name="java:/MyCF" pool-name="MyCF" enabled="true">
      <connection-factory-class-name>org.acme.ra.MyCF</connection-factory-class-name>
      <resource-adapter-archive>acme.rar</resource-adapter-archive>
   </no-tx-connection-factory>
</connection-factories>

(Full XSD to follow).

The question is really how much information we want to expose in domain.xml, as having all properties of all sub-systems exposed would quite a lot. But that is a question for another thread.

[dmlloyd]

Here's a question that applies to datasources as well as any other resource defined at the domain level.  How do we actually map these into server groups?  By usage?  What if we want to define more than one datasource with a given name (or rather, with a given JNDI binding) in the domain and map them selectively to server groups?

For deployments we have the file name + sha1.  In this case we could restrict a server group such that only one deployment with a given name is allowed per server group, or disambiguate some other way.  But for general resources we don't really have any sort of policy.

[jesper.pedersen]

Well, there are two cases here really.

1. The actual resource adapter archive
2. The activation of the resource adapter archive

1) This is the deployment of the myra.rar file which basically registers the resource adapter with the JCA container.

2) The activation actually deploys and registers the JNDI name for the connection factories.

An example would be the JDBC resource adapter -- its the same resource adapter archive, but you have multiple activations of the archive (java:/PostgreSQL, java:/OracleDS, ...).

For some resource adapters there will be a "standard" for its JNDI name, so this information can be supplied in the jboss-ra.xml like the other vendors do.

If non of the services at domain level requires f.ex. a datasource then we can move the definitions to the server group -- or let a definition at the server group level override the domain level one. We must make sure that the applications (or other services) defines a dependency on the JNDI name or pool name, so we know which definition is needed. Typically I would say that a deployment in this area is specific to an application, so people wants to be able to deploy the resource adapter along side their application -- f.ex. WS/EJB interface for an EIS.

[maeste]

Hi,

work on this area is going on: here you have the first draft of datasource_1_0.xsd

Even if it can be considered quite stable, it can change a bit in next future for usability reasons and/or...bugs

Here you have also all examples foundend in AS6 docs/examples/jca regarding datsource and xa-datasource rewritten according new xsd and used in our test suite.

Any comments are more than welcome

bye

S.

[jesper.pedersen]

Looks good. A couple of comments

I think we should remove the -settings suffix - f.ex. 'validation-settings' -> 'validation'.

Also we need a way to pass in configuration properties and their values to the user supplied classes like the validation connection checker and the exception sorter to allow user to override default values in the implementation.

F.ex. overriding the timeout value for the database ping method:

<valid-connection-checker>
<class-name>com.mycompany.MyConnectionChecker</class-name>
  <property name="Timeout">1</property>
</valid-connection-checker>

or something like that.

However, that can come later (post M1), as we need to enhance the JDBC resource adapter with this feature too.

[jason.greene]

Fantastic.

There are a few of couple the schema brings up that we need to figure out

1. We need to figure out how security is going to look, and how it can be commonly referenced from multiple areas, this is something we need to work with Anily and Scott on.
2. We need to figure out how a datasource gets at the class-loading module which contains the jdbc drivers and conection classes. This could mean a module descriptor reference, or alternative some kind of special namespace that is shared for drivers and datasources.

[jesper.pedersen]

I have been thinking about the configuration for the JCA container - e.g. <jca-container>.

I think that we should start by exposing some of the attributes that IronJacamar currently have on its deployer in order for users to setup their BootstrapContext's (DefaultBootstrapContext should be an internal thing), enable archive validation and bean validation.

So we will have

• ArchiveValidation
• ArchiveValidationFailOnWarn
• ArchiveValidationFailOnError
• BeanValidation
• BootstrapContexts

exposed in the configuration. See http://docs.jboss.org/ironjacamar/userguide/en/html/configuration.html#jca_deployer for all supported properties in the standalone environment.

The rest will resolved internally.

However, for BootstrapContexts we need to 'build' based on a thread group and thread pools, so there should be an element for that (<bootstrap-context>).

More advanced options - like selecting specific component implementations of the container - can come later.

[maeste]

Jesper Pedersen wrote:

Looks good. A couple of comments

I think we should remove the -settings suffix - f.ex. 'validation-settings' -> 'validation'.

Done in my last commit, with changes to metadatas interfaces and implementation according.

In this commit I've also changed a bit xsd to adhere xsd name comnvention of AS7 (mainly *Type for type definition instead of *ComplexType or *Value I've used before for complex and simple types) as I discussed in IRC with David.

Jesper Pedersen wrote:

Also we need a way to pass in configuration properties and their values to the user supplied classes like the validation connection checker and the exception sorter to allow user to override default values in the implementation. F.ex. overriding the timeout value for the database ping method:

<valid-connection-checker>

<class-name>com.mycompany.MyConnectionChecker</class-name>

  <property name="Timeout">1</property>
</valid-connection-checker>

And what about making class name an attribute? It wpuld results in a more compact xml in case of no property, and an easier to read one in case of multiple config property:

<valid-connection-checker class-name="com.mycompany.MyConnectionChecker" />

<valid-connection-checker class-name="com.mycompany.MyConnectionChecker">
     <property name="Timeout">1</property>
     <property name="OtherProperty">2</property>
</valid-connection-checker>

Jesper Pedersen wrote:

However, that can come later (post M1), as we need to enhance the JDBC resource adapter with this feature too.

Well, if we can agree at least on the xsd structure I'd prefer to change xsd now, to limit (as much as possible) changes in metadatas api.

best regards

S.

[maeste]

Hi all,

I've discussed a bit about this point with  Alexey Loubyansky on IRC channel. I was asking some feedback about the posted xsd.

I'm trying to write down the main contents of our discussion here to keep others post and then I'll try to resume our conclusion about how many xsd we need to have JCA stuffs included in domain.xml and also usable for standalone version of IronJacamar project. Please note here we are referring to a standalone JCA implementation and not standalone configuration of As for which we don't need anything different than domain.xml from a JCA config point of view.

Of course if I've missed and/or misunderstood something, Alexey please precise that points.

Feedback

The main points Alexey had about the xsd is:

• Name conventions (also David had pointed me out on this point). STATUS ON THIS POINT: I've already fixed type names in last committed version of xsd. I've tried to follow what I can see for example in /jboss-as-domain/src/main/resources/schema/jboss-domain-mod_cluster.xsd. Anyway have a look to the last committed xsd and let me know if something still missed/wrong.
• namespace: I need to define the namespace used for jca definition. Conventional namespace name is "urn:jboss:domain:whateveryouwant:1.0". STATUS ON THIS POINT: the namespace will be set in the top level xsd (let me call it jca.xsd) which will include other xsd (see conclusion)
• Number of xsd. I've explained I was planning to have different xsds for datasources (the committed one) and for connection-factories. Alexey thinks it's better to have just one xsd with multiple top-level element possible to limit the number of xsd, and much more important limit the number of namespaces. STATUS ON THIS POINT: see the next feedback and the conclusion. We agreed about an xs:include based solution giving multiple xsds file included in jca.xsd file with only one namespace used into the AS domain.xml
• I've explained to Alexey that IronJacamar (JCA project) needs these xsds too while it doesn't need a top level jca root tag with globla configuration. As Jesper explained in a previous post AS7 jca stuffs need some global configuartions (ArchiveValidation, ArchiveValidationFailOnWarn etc) exposing some of the attributes that IronJacamar currently have on its  deployer in order for users to setup their BootstrapContext's.  STATUS ON THIS POINT: see conclusions.

Conclusions

• We need at least 3 xsd: jca.xsd for AS7 and an xsd for ironJacamar stanalone. The first one will define  urn:jboss:domain:jca:1.0 namespace, tags for global configs and will include datasources and connectionfactories xsds (one containing both or 2 xsd at this level isn't a big difference). The second one just define a root tag, with its own namespace and will include DS and CF stuffs. The best solution we see (at xsd level) is to define DS and CF xsds without namesapce and then use in the 2 top level xsd (AS and JCAStandalone) xs:include directive to include all definition there. These solution should permit us to have in fact common definitions defined in DS&CF xsd (or 2 xsds as said, since using include it's just matter of number of files and not namespaces), and specific definitions in jca's AS xsd and ironJacamar standalone one. These is an advantage because we could have different life cycle for different configuaration levels, permitting in particular to add something at AS or standalone top level configs without impact each other.

Any comments are more than welcome

regards

S.

[jesper.pedersen]

Sure, moving the class-name definitions to an attribute would benefit the format

[jesper.pedersen]

namespace: I need to define the namespace used for jca definition. Conventional namespace name is "urn:jboss:domain:whateveryouwant:1.0". STATUS ON THIS POINT: the namespace will be set in the top level xsd (let me call it jca.xsd) which will include other xsd (see conclusion)

We will need to see where it fits into the overall AS 7 domain.xml picture -- configuration of the JCA container, setting up datasources and activating resource adapters are very different things, so I don't think putting them under a single XSD is a good idea.

Number of xsd. I've explained I was planning to have different xsds for datasources (the committed one) and for connection-factories. Alexey thinks it's better to have just one xsd with multiple top-level element possible to limit the number of xsd, and much more important limit the number of namespaces. STATUS ON THIS POINT: see the next feedback and the conclusion. We agreed about an xs:include based solution giving multiple xsds file included in jca.xsd file with only one namespace used into the AS domain.xml

No, those are separate because of the reasons stated above. Each piece will fit into a certain area in the domain.xml and not under a single tag.

We have

• The actual deployment (part of domain.xml which identifies the resource adapter archive)
• The configuration of the JCA container (settings for the JCA deployers and the container itself based on the JCA container XSD)
• Datasources (specification of datasources based on the datasources XSD)
• Activation of resource adapters (activation of resource adapter instances with their configuration based on the resource adapter XSD)

The question is if the "system" resource adapter such as jdbc-local.rar and jdbc-xa.rar should be hidden from the domain.xml and be a mandatory deployment. I think so, as <datasource> wouldn't work otherwise.

jca.xsd for AS7 and an xsd for ironJacamar standalone

No, and IronJacamar standalone issues should be discussed in the JCA Devel forum - they don't belong here.

These is an advantage because we could have different life cycle for different configuaration levels, permitting in particular to add something at AS or standalone top level configs without impact each other.

IronJacamar have a strict release cycle, so don't make that the first overall design goal. Remember that AS 7 will consume an IronJacamar tag which maps to certain functionality - the integration will live in AS 7.

[maeste]

Jesper Pedersen wrote:

I have been thinking about the configuration for the JCA container - e.g. <jca-container>.

Hi I have completed the xsd design and service implementation for JCA-container (connector subsystem).

I have just requested the pull to mantainers, but if someone would have a look it will be found on my git space

http://github.com/maeste/jboss-as

under connector module.

just to keep everyone up to date on work going on in this area, and have some feedbacks too.

bye

S.