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: 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



From: Mary McRae <mary.mcrae@oasis-open.org>
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>
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:  
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
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:
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
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:
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
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:
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
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:
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]