[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]