[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [sca-j] Re: Code Artifact Links and Layout.
Mary,
Placing links on the cover page of the CAA specification is no problem.
Where to place them is a problem. Is it ok if we add a new section on the
cover page? The Assembly test suite documents use the "Related Work"
section, but that doesn't seem appropriate since these code artifacts are
normative along with the spec. The only section close to what we want is
the Declared XML Namespace section, but that doesn't work because we're not
talking about XML namespaces.
WRT your second point, the SCA-J specifications do not have their own
namespace and therefore don't have their own namespace document, they share
the namespace document with the Assembly TC. Is that the namespace
document that you were referring to? If so, then we're in agreement with
you on this point.
Bryan, I added you because I think my email will bounce off the cpp list.
Dave Booz
STSM, BPM and SCA Architecture
Co-Chair OASIS SCA-Policy TC and SCA-J TC
"Distributed objects first, then world hunger"
Poughkeepsie, NY (845)-435-6093 or 8-295-6093
e-mail:booz@us.ibm.com
|------------>
| From: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Mary McRae <mary.mcrae@oasis-open.org> |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| To: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Mike Edwards <mike_edwards@uk.ibm.com> |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Cc: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|Jeff Mischkinsky <jeff.mischkinsky@oracle.com>, sca-c-cpp@lists.oasis-open.org, "OASIS Java" <sca-j@lists.oasis-open.org> |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Date: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|02/24/2010 08:56 AM |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|------------>
| Subject: |
|------------>
>--------------------------------------------------------------------------------------------------------------------------------------------------|
|[sca-j] Re: Code Artifact Links and Layout. |
>--------------------------------------------------------------------------------------------------------------------------------------------------|
Following the Assembly Test Suite, my recommendation is to:
1) Place links on the cover page
2) Include in the namespace document (since they are a resource and part of
the specification, just like any schema or wsdl files.
Mary
On Feb 24, 2010, at 4:43 AM, Mike Edwards wrote:
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: mike_edwards@uk.ibm.com
Fro Mary McRae <mary.mcrae@oasis-open.org>
m:
To: Mike Edwards/UK/IBM@IBMGB
Cc: Bryan Aupperle <aupperle@us.ibm.com>, Jeff Mischkinsky <
jeff.mischkinsky@oracle.com>, sca-c-cpp@lists.oasis-open.org, "OASIS
Java" <sca-j@lists.oasis-open.org>
Dat 23/02/2010 15:55
e:
Sub Re: Code Artifact Links and Layout.
jec
t:
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: mike_edwards@uk.ibm.com
From: Mary McRae <mary.mcrae@oasis-open.org>
To: Bryan Aupperle <aupperle@us.ibm.com>
Cc: Jeff Mischkinsky <jeff.mischkinsky@oracle.com>,
sca-c-cpp@lists.oasis-open.org
Date: 22/02/2010 17:58
Subje Re: [sca-c-cpp] Public Review of SCA Client and Implementation
ct: 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: aupperle@us.ibm.com
From: Mary McRae <mary.mcrae@oasis-open.org>
To: Bryan Aupperle/Raleigh/IBM@IBMUS
Cc: sca-c-cpp@lists.oasis-open.org, Jeff Mischkinsky <
jeff.mischkinsky@oracle.com>
Date: 02/20/2010 04:10 PM
Subje Re: [sca-c-cpp] Public Review of SCA Client and Implementation
ct: 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: aupperle@us.ibm.com
From: Mary McRae <mary.mcrae@oasis-open.org>
To: Bryan Aupperle/Raleigh/IBM@IBMUS
Cc: sca-c-cpp@lists.oasis-open.org
Date: 02/18/2010 01:49 PM
Subje Re: [sca-c-cpp] Public Review of SCA Client and Implementation
ct: 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: aupperle@us.ibm.com
From: Mary McRae <mary.mcrae@oasis-open.org>
To: members@lists.oasis-open.org, tc-announce@lists.oasis-open.org
Cc: OASIS TAB <tab@lists.oasis-open.org>,
sca-c-cpp@lists.oasis-open.org
Date: 02/14/2010 10:53 PM
Subje [sca-c-cpp] Public Review of SCA Client and Implementation Model
ct: 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: mary.mcrae@oasis-open.org
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
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]