---------------------------------------------------------------------------

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.