Re: [sca-c-cpp] NEW ISSUE: Should the C++ SCA spec define annotations

This issue has been assigned id CCPP-31
in the Jira system. 

See http://www.osoa.org/jira/browse/CCPP-31

Andrew

____________________________________________________________

Andrew Borley

Websphere ESB Development

Tel: 245393 Ext: +44 (0) 1962 815393 Mob: +44 (0) 7971 805547

E-mail: 

Mailpoint 211, IBM (UK) Ltd, Hursley Park, Winchester, Hants, SO21 2JN

____________________________________________________________

"David Haney" <>
wrote on 14/12/2007 00:46:20:

> TARGET: C++ C&I Specification

> 

> DESCRIPTION:

> Should the C++ spec define annotations for marking up source code
with

> SCA service information?  C++ does not natively define an annotation

> format or behavior, so annotations must be defined as a language

> extension that is both compatible with standard C++, and presumably
that

> would be parseable by an SCA defined parser.  If the spec should
define

> an annotation system for C++, we also need to define conformance

> guidelines for how those annotations will be used. (i.e., does the

> runtime need to parse the C++ in order to extract that information?
 Are

> annotations purely a design-time tool that allows code generation
of

> SCDL files? should annotations result in code that is compiled into
the

> library, that the runtime could query in order to extract a description

> of the service).

> 

> PROPOSAL:

> There seem to be three primary approaches that we could take towards

> annotations, each with their associated implications.

> 

> 1) Annotations are not defined by the spec.

> 

> The SCA runtime would rely solely on the SCDL files in order to describe

> a service, and would not make any attempts to parse the source files
at

> runtime.  This will require that some information to be duplicated

> between the source code and the SCDL files that describe the source.

> 

> The SCA spec would not attempt to define a mechanism for generating
SCDL

> files from the source.  It would leave it up to individual vendors
to

> define their own mechanism, which could be through the use of

> annotations, or could be through some other proprietary mechanism.

> Portability would be maintained at runtime in that each runtime would
be

> expected to consume SCDL files to retrieve description information,
and

> should be independent of whether the SCDL was written by hand or

> generated from the source.

> 

> This has the benefit of removing the need to define an annotation
system

> in C++.  Individual vendors would be free to define (or not define)

> they're own schemes for creating SCDL for C++ code.  Those schemes
could

> be annotation based, or could be provided by some other mechanism.

> 

> 

> 2) Annotations are a design-time tool to allow for generating SCDL

> files.

> 

> As in (1), the SCA runtime would still rely solely on SCDL files in

> order to describe the service; however the specification would also

> define a mechanism for marking up code so that the SCDL files could
be

> generated from the source.

> 

> This is relatively close to what the current system supports, however
it

> would clarify the role of annotations in the SCA runtime, and precedence

> rules for when information is defined in both the SCDL and in

> annotations (the canonical information would need to be in SCDL,

> annotations would not affect runtime behavior).

> 

> This has the same benefit as (1) in regard to defining where canonical

> information is stored at runtime, in the SCDL files.

> 

> If this was the approach we decided to pursue, would annotation support

> be required of a conforming implementation, or would this be a case

> where annotations are still optional, however if annotations are

> defined, they must follow this convention?

> 

> Since this isn't an issue for the runtime (it will still reference

> SCDL), who would the conformance statements apply to?  Is there
a

> conformance target for tools vendors (which could be independent of
the

> runtime vendors?).

> 

> 

> 3) Annotations are a runtime tool, allowing for programmatic

> introspection (and possibly design-time introspection as well).

> 

> This is probably the most complex solution; however it would also

> provide functionality that's closest to what's being provided by Java's

> annotations.  Under this mechanism, we would define an annotation
system

> in C++ that would allow us to introspect the class at runtime in order

> to derive information.

> 

> On a cursory review, there are two forms this could take.  One
would be

> to implement annotations through a macro-based system that would allow

> us to insert methods that would provide meta-data about a service
into

> the service itself.  Since C++ does not provide basic introspection
for

> classes (such as what methods a class provides), we would have to
go

> beyond the basic annotations that Java supports, and also define

> mechanisms for defining methods and their arguments through the

> annotations system as well.  This could quickly result in us
needing to

> define both the method and a macro with meta-information about the

> method for each method in the class.  This seems like its going
well

> beyond what the language would normally support, and is probably on
the

> level of supporting dependency-injection, which we've implied is beyond

> the scope of what we want to tackle in the spec at this point.

> 

> A second approach would be to generate a wrapper class around the
user's

> class that would provide the meta-information.  The runtime could
then

> query this code-generated class at runtime in order to extract

> information.  This would require annotations similar to what's
required

> in (2).  I'm not sure this would provide any benefit over parsing
the

> SCDL file to retrieve this information (as in 2), and would mandate
more

> about the runtime implementation than in (2).

> 

> There may be further options for how we could achieve (3) that would

> eliminate some of the drawbacks outlined here.

> 

>  

> On a first pass, (2) seems like it may be the safest choice.  This
would

> maintain most of the compatibility with what was defined in OSOA 1.0,

> however it would also clarify the role of annotations, which should
make

> writing conformance guidelines cleaner (and easier for vendors to

> implement).  (1) however is also very tempting, as it would greatly

> simplify the spec (eliminating all discussion of annotations), and
would

> provide vendors more flexibility in how they want to generated SCDL
from

> source.  Assuming we make supporting annotations optional, I
believe (1)

> becomes a degenerate case of (2), as a complying vendor could opt
out of

> supporting annotations, and could still provide an alternative mechanism

> for generating SCDL.

> 

> A fourth option might be to go with (1) for the main specification,

> however to also provide a supplementary specification that defines

> conformance for a tool vendor to generate SCDL from source code.  This

> could even be a non-normative document that just provides a recommended

> annotation format.

> 

> Thanks.

> 

> David.

> 

> 

> -- David Haney

> -- Chief Architect, Hydra Products

> -- Rogue Wave Software

> -- http://www.roguewave.com/ 

> 

> 

> 

> ---------------------------------------------------------------------

> To unsubscribe from this mail list, you must leave the OASIS TC that

> generates this mail.  You may a link to this group and all your
TCs in OASIS

> at:

> https://www.oasis-open.org/apps/org/workgroup/portal/my_workgroups.php

> 

Unless stated otherwise above:

IBM United Kingdom Limited - Registered in England and Wales with number
741598. 

Registered office: PO Box 41, North Harbour, Portsmouth, Hampshire PO6
3AU