Mary,
I think you may have misunderstood my
email.
My email was about the Test Suite, not
the main Assembly specification.
I am pointing out that the Assembly
Test Suite, which does have a specification document of its own, is a precedent
for the handing
of a specification document that has
associated code artifacts.
In the case of the Java and C++ SCA
specifications, the main specification itself has code artifacts - and
I am suggesting
that these code artifacts are treated
by those specifications in the same way that the code artifacts are treated
by the
test suite specification. These
artifacts are NOT test suite artifacts and are described already in the
body of the specification
itself so that there is no justification
or need to create a separate specification document which describes them.
Thus, I propose that for the SCA Java
CAA specification:
1) Links are placed on the frontmatter
of the CAA specification which point to the locations of the code artifacts
2) The code artifacts consist of:
- the Binary JAR file
- the Source ZIP file
- the source files in expanded directory
layout
- the Javadoc files
all these artifacts should be loaded
to the OASIS site and be available publicly as specification artifacts.
Yours, Mike.
Strategist - Emerging Technologies, SCA & SDO.
Co Chair OASIS SCA Assembly TC.
IBM Hursley Park, Mail Point 146, Winchester, SO21 2JN, Great Britain.
Phone & FAX: +44-1962-818014 Mobile: +44-7802-467431
Email:
From:
Mary McRae <>
To:
Mike Edwards/UK/IBM@IBMGB
Cc:
Bryan Aupperle <>,
Jeff Mischkinsky <>, ,
"OASIS Java" <>
Date:
23/02/2010 15:55
Subject:
Re: Code Artifact Links and Layout.
Hi Mike,
I don't think that's accurate.
The SCA Assembly specification is here:
http://docs.oasis-open.org/opencsa/sca-assembly/sca-assembly-1.1-spec.html
It makes no mention of the test cases on the cover page.
What they did - and what I think the other TCs should
do as well - is to create a separate document that describes the testcases:
http://docs.oasis-open.org/opencsa/sca-assembly/sca-assembly-1.1-testcases-cd01.html
They are also identified in the namespace document:
http://docs.oasis-open.org/ns/opencsa/scatests/2009032
I'd like to see the other TCs do the same and follow SCA
Assembly's lead.
Mary
On Feb 23, 2010, at 5:07 AM, Mike Edwards wrote:
Mary,
There is some precedence for dealing with code artifacts related to OASIS
TC specifications.
As a first point, I think that in general all the artifacts are indeed
described somewhere in the specification document(s) under
consideration. The main consideration is that in general code artifacts
are organized into packages, somewhat analogous to
namespaces for XML documents, but that the conventions and formalisms for
code artifacts do differ from those that apply to
XML artifacts. For example, there is nothing quite equivalent to
the namespace URL and there is as a result no obvious location
at which you would expect to find a given code artifact.
So, to take Java code as a particular case. Java code is organised
into packages - and packages do imply a relative directory
hierarchy which directly reflects the package naming. So, to take
an example from the OASIS SCA-J TC, there is the ComponentContext
interface, which is in the "org.oasisopen.sca" package. This
implies a directory structure like this:
org
- oasisopen
- sca
with the file ComponentContext.java contained in the "sca" directory
(along with a group of other files that are in the SCA-J API)
However, in this case, the "org" directory can then be placed
into some arbitrary other directory at the choice of the publisher.
In the OASIS SVN repository, it is placed into a directory src/main/java,
following conventions used by build systems including Maven
and Eclipse.
The binary code files (ie compiled form) for these source code files are
organized similarly, but in Java, they are organized into JAR
files, which are basically ZIP files with a specific form of Manifest.
Within the ZIP file, the relative directory structure is preserved.
Thus,
all the files in the Java CAA specification are compiled into the file
sca-caa-apis-1.1-CD04.jar (for example) and inside that jar file,
the directory structure org/oasisopen/sca appears, containing ComponentContext.class
(amongst others).
So, the question at issue is where the various artifacts get published
on the OASIS system.
The precedence I'd like to look at concern the SCA Assembly Test Suite.
This is a formal specification document, published here:
http://docs.oasis-open.org/opencsa/sca-assembly/sca-assembly-1.1-testcases-cd01.pdf
This Test Suite has a pile of associated artifacts - XML files of various
forms and also code artifacts including Java and C++ code files.
The artifacts are available in a ZIP file, which has a reference under
the "Related Work" item on the frontmatter:
http://docs.oasis-open.org/opencsa/sca-assembly/sca-assembly-1.1-testcases-cd01.zip
I note that the same set of artifacts are available in an "unpacked"
form at the following address:
http://docs.oasis-open.org/opencsa/sca-assembly/sca-assembly-1.1-testcases-cd01/
- however this address is not mentioned in the frontmatter of the specification
document (it probably should be).
The test suite artifacts are then described in various places throughout
the document.
Now "Related Work" may not be the best possible location for
the links to these artifacts, although it seems OK to me.
Perhaps the right place in many ways is similar to "Declared XML Namespaces"
but perhaps should be called
"Declared Code Artifacts" or some such - certainly for Java,
the use of a given Java package name is important - it
must not clash with other code in exactly the same way that XML namespaces
must not clash. However, a Java package
name is not an XML namespace.
So - shall we simply follow the convention used by the SCA Assembly Test
Suite or do you want to organize it differently?
Yours, Mike.
Strategist - Emerging Technologies, SCA & SDO.
Co Chair OASIS SCA Assembly TC.
IBM Hursley Park, Mail Point 146, Winchester, SO21 2JN, Great Britain.
Phone & FAX: +44-1962-818014 Mobile: +44-7802-467431
Email:
From:
Mary McRae <>
To:
Bryan Aupperle <>
Cc:
Jeff Mischkinsky <>,
Date:
22/02/2010 17:58
Subject:
Re: [sca-c-cpp] Public Review of SCA
Client and Implementation Model for C and C++ Specifications - 15 day review
Seems like they should be included as a Normative Reference, listed as
an artifact in the namespace document, noted on the cover page of the spec
... something. Without an explicit reference how would anyone know where
to find them?
I'm happy to work with a team of representatives from each TC or the liaisons
subcommittee to work out something that will be applied consistently across
all of the TCs.
The next question would be if that code is authoritative, what standing
does it have within the TC? Shouldn't there be a document that describes
the artifacts and that document, along with the artifacts themselves, voted
and approved at each stage? Submitted for public review?
Mary
On Feb 22, 2010, at 12:37 PM, Bryan Aupperle wrote:
They are not explicitly referenced by name or URI, but there is a statement
in the conformance section stating that there are source code artifacts
and that they are authoritative over the spec text relative to the API
definition.
If necessary, it would be reasonable to have them put in a zip and have
a link in some appropriate place in the specification.
I know the Java TC is discussing essentially the same concern.
Bryan Aupperle, Ph.D.
STSM, WebSphere Enterprise Platform Software Solution Architect
Research Triangle Park, NC
+1 919-254-7508 (T/L 444-7508)
Internet Address:
From:
Mary McRae <>
To:
Bryan Aupperle/Raleigh/IBM@IBMUS
Cc:
,
Jeff Mischkinsky <>
Date:
02/20/2010 04:10 PM
Subject:
Re: [sca-c-cpp] Public Review of SCA
Client and Implementation Model for C and C++ Specifications - 15 day review
Thanks Bryan.
Sorry, but more questions. Are they actually referenced in the specification
somewhere or noted in the namespace document? If not, is there some other
document that will be describing them/referencing them? How is someone
to know that they exist or should be used? Are they part of the specification
or some ancillary support material with no official standing within the
TC?
I have no objections to uploading them per se, but if they aren't part
of the specification and not referenced anywhere it doesn't make much sense.
Mary
On Feb 18, 2010, at 2:10 PM, Bryan Aupperle wrote:
It is a file in C or C++ that is used to define an API. A header
file normally has an extension of .h and is used when compiling a program.
I.e. a machine readable version of an API definition.
Bryan Aupperle, Ph.D.
STSM, WebSphere Enterprise Platform Software Solution Architect
Research Triangle Park, NC
+1 919-254-7508 (T/L 444-7508)
Internet Address:
From:
Mary McRae <>
To:
Bryan Aupperle/Raleigh/IBM@IBMUS
Cc:
Date:
02/18/2010 01:49 PM
Subject:
Re: [sca-c-cpp] Public Review of SCA
Client and Implementation Model for C and C++ Specifications - 15 day review
I'm going to now ask a stupid question (sorry!): What's a header file?
Mary
On Feb 18, 2010, at 1:31 PM, Bryan Aupperle wrote:
The zip packages we sent for this PR included some header files. If
I look at http://docs.oasis-open.org/opencsa/sca-c-cpp/
I do not see any of the header files. What do we need to do to get the
header files published?
Thanks.
Bryan Aupperle, Ph.D.
STSM, WebSphere Enterprise Platform Software Solution Architect
Research Triangle Park, NC
+1 919-254-7508 (T/L 444-7508)
Internet Address:
From:
Mary McRae <>
To:
,
Cc:
OASIS TAB <>,
Date:
02/14/2010 10:53 PM
Subject:
[sca-c-cpp] Public Review of SCA Client
and Implementation Model for C and C++ Specifications - 15 day review
To OASIS members, Public Announce Lists:
The OASIS Service Component Architecture / C and C++ (SCA-C-C++) TC has
recently approved the following specifications as a Committee Draft and
approved them for public review:
Service Component Architecture Client and Implementation Model for C++
Specification Version 1.1
Service Component Architecture Client and Implementation Model for C Specification
Version 1.1
The public review starts today, 15 February 2010, and ends 2 March 2010.
This specification was previously submitted for a 60-day public review
on 24 April 2009[1]; this 15-day review is limited in scope to changes
made from the previous review. All changes are marked.
This is an open invitation to comment. We strongly encourage feedback from
potential users, developers and others, whether OASIS members or not, for
the sake of improving the interoperability and quality of OASIS work.
More non-normative information about the specification and the technical
committee may be found at the public home page of the TC at:
http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=sca-c-cpp.
Comments may be submitted to the TC by any person through the use of the
OASIS TC Comment Facility which can be located via the button marked "Send
A Comment" at the top of that page, or directly at:
http://www.oasis-open.org/committees/comments/index.php?wg_abbrev=sca-c-cpp.
Submitted comments (for this work as well as other works of that TC) are
publicly archived and can be viewed at:
http://lists.oasis-open.org/archives/sca-c-cpp-comment/.
All comments submitted to OASIS are subject to the OASIS Feedback License,
which ensures that the feedback you provide carries the same obligations
at least as the obligations of the TC members.
The specification documents and related files are available here:
Service Component Architecture Client and Implementation Model for C++
Specification Version 1.1
Editable Source:
http://docs.oasis-open.org/opencsa/sca-c-cpp/sca-cppcni-1.1-spec-cd03.doc
PDF:
http://docs.oasis-open.org/opencsa/sca-c-cpp/sca-cppcni-1.1-spec-cd03.pdf
HTML:
http://docs.oasis-open.org/opencsa/sca-c-cpp/sca-cppcni-1.1-spec-cd03.html
Namespaces:
http://docs.oasis-open.org/ns/opencsa/sca/200903
http://docs.oasis-open.org/ns/opencsa/sca-c-cpp/cpp/200901
Service Component Architecture Client and Implementation Model for C Specification
Version 1.1
Editable Source:
http://docs.oasis-open.org/opencsa/sca-c-cpp/sca-ccni-1.1-spec-cd04.doc
PDF:
http://docs.oasis-open.org/opencsa/sca-c-cpp/sca-ccni-1.1-spec-cd04.pdf
HTML:
http://docs.oasis-open.org/opencsa/sca-c-cpp/sca-ccni-1.1-spec-cd04.html
Namespaces:
http://docs.oasis-open.org/ns/opencsa/sca/200903
http://docs.oasis-open.org/ns/opencsa/sca-c-cpp/cpp/200901
OASIS and the SCA-C-C++ TC welcome your comments.
Mary P McRae
Director, Standards Development
Technical Committee Administrator
OASIS: Advancing open standards for the information society
email:
web: www.oasis-open.org
twitter: @fiberartisan #oasisopen
phone: 1.603.232.9090
[1] http://lists.oasis-open.org/archives/tc-announce/200904/msg00011.html
---------------------------------------------------------------------
To unsubscribe from this mail list, you must leave the OASIS TC that
generates this mail. Follow this link to 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
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
