users@connector-spec.java.net

[connector-spec-users] [jsr322-experts] Re: Deployment annotations

From: Sivakumar Thyagarajan <sivakumar.thyagarajan_at_oracle.com>
Date: Wed, 23 Jan 2013 10:30:49 +0530

Hi Jesper

On Wednesday 23 January 2013 12:51 AM, Jesper Pedersen wrote:
> Hi,
>
> On 01/21/2013 08:38 AM, Sivakumar Thyagarajan wrote:
>>> However, the actual deployment of the ResourceAdapter instance is done as
>>> part of the vendor specific activation giving:
>>
>> The deployment of the RA is a 'module' deployment and there exists
>> JSR-88 like APIs to deploy a RAR, and this IMHO should not be linked
>> with resource definition annotations.
>>
>
> What do you mean by this ?

I meant that we should decouple the deployment of the resource adapter
module (or activation as you call it) from the creation of resources (like
ConnectionFactory and AdministeredObject), with respect to the resource
definition annotations. This decoupling doesn't prevent us to move to a
scoped model (that you had proposed in the thread) in the future.

A vendor may allow a vendor-specific mechanism to deploy a resource
adapter and include CFs and AOs as part of it. This has to be in
*addition* to what the Platform spec requires (EE.8.1.1) in terms of
module names. The former is vendor-specific, whereas the latter is what
the Platform defines. We *can* only realistically design for the latter.

>>> Configuration Annotations
>>>
>>> (CF) CF
>>> | |
>>> RA-------- resource-adapter-name ------
>>> | |
>>> (AO) AO
>>>
>>> where 'Configuration' is the vendor specific part, and 'Annotations' is
>>> the annotations defined in the specification.
>>
>> In the left hand side of the figure, should we read the (CF) and (AO)
>> are as entities created by the container automatically based on CF and
>> AO resource definition annotations placed in the application?
>>
>
> No, the 'Configuration' side of the diagram is the deployment / activation
> of the resource adapter instance with a given 'resource-adapter-name'.
> This deployment has at least a ResourceAdapter instance. However, there
> may be ConnectionFactory's and AdminObject's too.
>

Ok, so in your diagram (CF) and (AO) on the LHS are already created
through vendor-specific means. CF and AO on the RHS are new resource
definitions specified through annotations.

> The 'Annotations' side of the diagram is the application where the
> resource adapter deployment annotations are located.
>
>>> The resource-adapter-name field must clearly identify which deployment
>>> they belong to. The identifier is vendor specific though and may not even
>>> be available depending on the vendors deployment model.
>>
>> The EE platform requirements in Section EE.8.1.1 (in para starting with
>> 'All Java EE modules have a name.') indicate that all deployed modules
>> must have a 'name' and it is defaulted to the specified name of the
>> moduls. There are cases where (in the case of conflicts only) the
>> deployment tool can, in a vendor-specific manner, devise a name EE.8.1.1.
>>
>> So, the point about no names being available is invalid in an EE
>> application server. We have talked about standalone connector containers
>> in another thread and that is a whole new ball game.
>>
>>> This results in that vendor specific overrides are required, since a
>>> standard format of the field can't be specified. This limits the
>>> usability
>>> of the annotations.
>>
>> The name is only vendor-specific if it's not unique. If the resource
>> adapter is bundled with the application, the application assembler can
>> ensure that module names are unique.
>>
>> So though the resource-adapter-name may be vendor-specific in some
>> cases, in most cases (arguably 99% of the time) the name is known ahead
>> of time.
>>
>> It is well known for embedded RARs (when the application assembler
>> ensures there are no name conflicts in the EAR), and for standalone RARs
>> where the target RAR is known. Since this name is known ahead of time,
>> such vendor-specific overrides should be few.
>>
>> Due to these reasons, I don't understand why we would need to define the
>> scoped deployment model you outline below.
>
> I think I have explained why this won't work in real life, making the
> annotations useless.

With the naming rules defined in EE.8.1.1, why wouldn't it work in real
life? An application server vendor is required to support the names as
defined in EE.8.1.1. This name should be usable in the majority of the
scenarios.

As an example, if a standalone resource adapter module foo.rar is
deployed, the deployed RA modules's name must be "foo", and this is
available for an application component's resource definition annotations
to refer to. This doesn't need to change during deployment for most scenarios.

It is only cases where vendor-specific means are used to deploy the
standalone resource adapter and that uses a vendor-specific naming scheme,
would an application deployer need to override the resource-adapter-name
"foo" specified in a resource definition annotation of the component.
Again, this is possible through deployment-descriptors.

We can't define for these vendor-specific cases as they are
vendor-specific and we can't predict all models out there.

> Counting on 'everything is default' is going to break the first time a
> simple change is made somewhere.
>
> Having a model where everything is explicit defined is the best way to
> handle this scenario. Or not doing it at all.

The proposed model (@ResourceAdapterDeployment) in this thread ties the
deployment and configuration of a module with resource definitions using
lexical scoping of annotations, and this is IMO more complex and less
flexible.

Even if we want to move to this model in the future, I don't see why this
can't work with the resource definition annotations (The
@ResourceAdapterDeployment could have a name so that other entities can
refer to it, and this could be used in the resource-adapter-name of the
new resource definition annotations).

Thanks
--Siva.