OASIS Mailing List ArchivesView the OASIS mailing list archive below
or browse/search using MarkMail.


Help: OASIS Mailing Lists Help | MarkMail Help

sca-c-cpp message

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]

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

TARGET: C++ C&I Specification

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).

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

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.



-- David Haney
-- Chief Architect, Hydra Products
-- Rogue Wave Software
-- http://www.roguewave.com/ 

[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]