---------------------------------------------------------------------------
Building the schemas:

1. Create a child teamware workspace of /java/j2ee/XMLSchemas/deployment

   bringover -w ~/xmlschemas-deployment -p /java/j2ee/XMLSchemas/deployment .

      or

   cd ~/xmlschemas-deployment
   bringover

   This is the workspace that Umit created before she left.
   It contains all the J2EE schemas in it
   The *.xsds files are the source files for the .xsd output files.
   They contain things like #include that are not valid .xsd but this
   allows us to more easily maintain our schemas.

2. Type make
   This will produce *.xsd and *.mif for inclusion in the spec.

3. Read the README file (included below), in particular the "THINGS YOU SHOULD KNOW IN
   USING MIF" section.  This section will tell you the correct way to
   import the mif into the spec chapter.  Yes, more manual steps :(

Modifying the schemas:

1. Edit the .xsds file for web-jsptaglibrary_2_1.xsd or jsp_2_0.xsd
   (eventually we need to create a jsp_2_1.xsd as well).
2. Run make to generate the .xsd
3. cd testarea/
4. Edit the taglib-2_1.xml or web-app.xml to write a test case for the new
   changes to the schema.
5. Run 'make jsp-tld' or 'make web-app' to test the TLD or JSP portion
   of the web.xml, respectively.
6. If the tests pass, check in the new test and schema
7. Build the schema as above and update the spec chapter
8. Update the .vthought diagrams for the TLD, if necessary
9. Check the latest version of the .xsd schemas into the
   jakarta-servletapi-5/src/share/dtd directory and commit the changes.

Hope this helps!
- Mark 

---------------------------------------------------------------------------
Publishing the schemas
---------------------------------------------------------------------------
Bill,

I just put back the first revision of the JSP 2.1 TLD schema to our
/java/j2ee/XMLSchemas/deployment workspace.

I just wanted to verify with you that we're still going to use this
same workspace for our J2EE 5.0 schemas.

I had to modify Makefile to build both JSP 2.0 and JSP 2.1 schemas.
The previous Makefile assumed that only one version could be built at
a time.

-----
Yes, I was planning to continue to use that workspace.

When you're ready to publish your new schema to the web, let me know.

-----
The current plan of record is for JSP and JSF to hand our respective
EDRs to the JCP on December 3.

When do you recommend we publish the schema to the web?  Can it be done after EDR?

-----
Yes.  When you publish is up to you.  Publish it when you think a lot of
people will go to the web site looking for it.

---------------------------------------------------------------------------
TLD Diagram
---------------------------------------------------------------------------
Pierre,

Attached is the MIF (and .vthought source) to replace the diagram in the 
TLD chapter for the JSP 2.1 TLD.

Do you have any .vthought files in your repository?  For some reason
it said that it wasn't part of the repository.  Maybe I never checked
them in?

I just noticed I could have done a better job with the schema and
prevented the user from specifying both <deferred-value> and
<deferred-method>, but this should do for now.  I'll see if I can fix
that before EDR.

Let me know if you have any trouble integrating the new diagram or
schema into the spec.

- Mark

TOOL is: Visual Thought (confluent www.confluent.com)

=============================================================================
README from xmlschemas-deployment

HOW TO USE SCHEMA GENERATOR: 

Necessary Files: 

(1) This directory contains a copy of 

xml.xsd
XMLSchema.dtd
datatypes.dtd


The originals can be found in http://www.w3.org/2001 directory. They
are also in the source code repository. 

PLEASE USE THEM AS IS. w3c grants us use as is. The license issue was resolved
within the W3CLicense file. Please refer to it.

We use the local files for testing, because importing remote files to schema can
be problematic. This can be handled however by reusing a local copy of the
files.

(2) You have several common files which you should include into your spec with
#include. They MUST BE included as annotations (XML Schema comments) to your
spec.

annotations: contain copyright information that is generated by Bonnie which
MUST BE included in the preemble of each schema file

glossary: Definition of common terms that are defined in common schemas such as
j2ee_<version>.xsds that adopts its meaning given the scope it is included in.

common: conventions that will apply to all files

The best thing is to look at one of the .xsds files to see an example to use
#include.


HOW TO USE THIS DIRECTORY:


-- Create an .xsds file. This is the source document for a schema file. Some
guidelines:

    -- Each line in the .xsds file should be at most 70 characters. 

    -- Provide a 
       <xsd:annotation>
       <xsd:documentation>
       ...
       block as comments for each type or element you create.
       DO NOT use XML comments. This is markup and the documentation of each
       element follows the declaration as you use other tools, such as XML Spy.

       Escape any sample XML markup used as documentation.  The recommended
       way to do this is to use a CDATA section.  For example,

       <xsd:documentation>
       <![CDATA[

       Any documentation including markup can go here.
       For example: <a-tag>foo</a-tag>
 
       ]]>
       </xsd:documentation>

       See *.xsds file for other examples.  This prevents some conformant
       XSD processors from trying to validate the content of the
       <xsd:documentation> node itself, which would typically fail.

    -- Element declarations should have type, {min|max}Occurs in separate lines.

       I am not sure this rule totally makes sense b/c in a sense
       {min,max}Occurs attributes are related and it improves readability
       to have them on the same line.  Also, I see many places where they
       are on the same line so this guideline should probably be
       removed. [eeg 4oct02]

    -- Follow the indentation conventions. (For emacs, you should turn
       tabify off and use blanks instead). When in doubt, select the
       buffer and run M-x untabify.

    -- Use <xsd:group ref="j2ee:descriptionGroup"/> for consistency with
       the following convention: Don't forget to use description,
       display-name and icon elements in the order with minOccurs=0 and
       maxOccurs="unbounded". In the Schema version, we have xml:lang
       attributes which allow for separate languages to be used for each of
       these definitions.


-- Use the make file to generate your specs .xsd and .mif files. The
make file uses xsdc to make the xsd and mif files.

-- The targets in the Makefile are for each specification area: 
    all: for all specs
    web-app: servlet
    ejb-jar: ejb
    connector: as implied
    jsp: as implied
    jsp-tld: tag library
    platform: app-client, application and j2ee schemas
    j2ee: common j2ee schema only
    clean: removes mif, xsd, and class files. 

There are also targets to build the validator.jar file. Please see below
for the details. 


-- Use make file target to make your xsd file. 

-- You may get some errors. The xsdc compiler does several things: 

    -- Formatting (Including copyright file, common definitions, basically
       #includes);

    -- Sorting the definitions (The output includes the preemble and
       the top level element first, followed by sorted global types).

    -- Checking referenced but not existing definitions in your
       file. It does not load the definitions in the files that are
       referenced (Some of the references are not local). Therefore, if you
       have used common defs which are in j2ee_<*>.xsd files, you will get
       errors such as:
    
       ejb-jar_2_1.xsd: type deployment-extensionType referenced but never defined

       Please examine the error messages. If you think that there is a type
       which should have appeared in your xsd file but did not, revisit your
       .xsds file and fix the references to it. The types that are from
       referenced files will appear in the warnings, as shown in the example.

-- After you make your xsd file, cd to testarea and run tests for your spec.
   You should read the README in that directory. 

-- When you need to publish the schema, you should copy it to a different
   directory so that subsequent builds do not corrupt the schema, such as
   leighs_area directory.

-- The website is maintained by Bill Shannon. If you need help, see Bonnie.

MODIFYING THE VALIDATOR JAR: 

Please see the README file in the testarea for details. 


THE GORY DETAILS: 

xsdc is the xsd "compiler".  It's written in perl.

use commands:

sh ./xsdc <xsds_file> to generate an .xsd file.

sh ./xsdc -m <xsds_file> to generate the mif file.

THINGS YOU SHOULD KNOW IN USING MIF:

(A) You must first import the paragraph formats from new_formats_5.5.doc to your
specification. If this is already done, skip to (B).

Open the new_formats_5.5.doc document with framemaker. You will see the
instructions. However, here they are here for completeness:

    1. With the new formats file and your spec open, select
File->Import->Formats IN THE SPEC document.

    2. In the Import from Documentation box choose new_formats_5.5.

    3. Make sure that only the Paragraph Formats checkbox is selected.

    4. Click on the Import button.

    5. You should see 5 different paragraph formats in the available paragraphs
all named starting with "Schema-"

(B). Select a location to include the schema.

(C) File-Import-File and choose the mif file that corresponds to your schema,
i.e. ejb-jar_2_1.mif. Import the file.

(D) You should see the document nicely formatted, namely annotations are in
italics, the types are bold, etc.

OTHER STUFF:

There are several directories which are of interest:

- testarea/ contains an instance file to test your schema with.  You must run
the test in the area for sanity check of your schema.

- libraries/ contains the jar files to run the test script.

- string_usage.html contains the usage of string based content with respect to
each spec.

SRC FILE for VALIDATOR.JAR: 

Validation is enabled by building the validator.jar jar file which contains a 
simple validator. 

The src directory contains the source for the validator program. The makefile
targets that are relevant for building are: 

classes: makes the classes directory for class files. 
build: builds everything
validator.jar builds the validator.jar in the current directory. 

Please DO SET your JAVA_HOME env variable appropriately. 

The testarea requires a validator.jar to be present to be able to run the tests.

Please note the following:

    The validator program cheats by using a Properties file to get the schema
    that would be used for validating an instance document. In a real DD
    processing, a double pass for validation would be necessary to determine the
    version number and the schema document first and then use the information to
    drive the parser to validate with a specific schema file. In this version, I
    used a property file to drive the validator.

Please also see the README for adding additional tests by using the Property
files. 
