ECLIPSE WEB TOOLS PLATFORM developing java web applications PHẦN 10 potx

A public identifier (or publicId) provides no hint as to the actual location of

a schema or DTD but instead provides a unique identifier for the artifact that

you can use to determine the location by some other means (such as the XML

catalog). A schema’s public identifier is its namespace, such as

http://java.sun.com/xml/ns/j2ee

and is typically specified by declaring a namespace in an XML document (see

line 4 in Example 15.1 earlier). A DTD’s public identifier, typically specified in a

comment in the DTD, is specified in an XML file by using the PUBLIC keyword in

a DOCTYPE statement (see Example 15.2).

Example 15.2 J2EE 1.3 PUBLIC DOCTYPE

<!DOCTYPE web-app PUBLIC

"-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"

"http://java.sun.com/dtd/web-app_2_3.dtd">

A system identifier (or systemId) provides a hint as to the actual location of

a schema or DTD. A schema system identifier, typically a URL, is specified in an

XML file using the xsi:schemaLocation attribute. This attribute contains a list

of paired items, where the first item is the schema namespace and the second

item is the system identifier (see lines 6 and 7 in Example 15.1 earlier). A DTD

system identifier, also typically a URL, is specified in an XML file using the

SYSTEM keyword in a DOCTYPE statement (see Example 15.3).

Example 15.3 J2EE 1.3 SYSTEM DOCTYPE

<!DOCTYPE web-app SYSTEM

"http://java.sun.com/dtd/web-app_2_3.dtd">

Every J2EE Web application contains the XML file web.xml, known as the

deployment descriptor (see Example 15.1), which holds configuration details for

the application, such as servlet mappings. The deployment descriptor is located

in the web-inf folder in each application.

The deployment descriptor specifies the specific J2EE grammar it requires by

declaring a system identifier. For J2EE 1.4 the system identifier is

http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd

(There are different grammars for the different parts and versions of the J2EE

specification.) As mentioned earlier, having access to the file containing the J2EE

grammar will allow WTP’s tools to provide enhanced function for validation

and content assistance for web.xml.

Contributing Resources to the XML Catalog 649

By default, WTP will attempt to retrieve remote schemas and DTDs from the

Web and cache them using a cache resource resolution strategy. In the case of

J2EE, this allows WTP users to get the enhanced function even though the J2EE

schemas and DTDs are not bundled with WTP. Although this solution generally

works well, it does have a number of drawbacks for new users.

❍ New users must use WTP while connected to the Internet in order to

download these schemas and DTDs. This adds an extra configuration step

to the WTP install process and can lead to problems if the servers are not

visible (due to server outage, proxy configuration or some other problem)

when attempting to download the files.

❍ Creation of the first Web application will take longer than subsequent Web

applications as the user has to accept license agreements and download the

schemas and DTDs.

❍ Every new user must perform this operation. This reduces the efficiency of

your organization by placing a burden on all developers that use WTP,

increases bandwidth consumption, and may lead to an increase in support

calls if there are any network difficulties.

For these reasons you will bundle the J2EE schemas and DTDs with the ver￾sion of WTP your organization distributes internally, preventing the need for

WTP to retrieve the files remotely. In the following sections you will contribute

the J2EE schemas to WTP using WTP’s XML catalog.

The XML Catalog

WTP’s XML catalog allows you to register schemas and DTDs for use in

resource resolution. (The catalog can actually register any resource that can be

specified with a URI, such as a WSDL document. See the online documentation

on the WTP Web site for more about registering any resource.) Typically the

XML catalog is used in the way you are going to make use of it, to specify the

location of local schemas and DTDs. To put this function in resource resolution

terminology, the XML catalog implements a resource resolution strategy that

retrieves a specific resource from a catalog of resources using a key. In fact, the

XML catalog is a URI resolver that has been contributed to the URI resolution

framework, which you will make direct use of later in this chapter.

The XML catalog includes a graphical user interface (see Figure 15.2) that

allows you to easily contribute resources to it. Resources can be contributed through

the XML catalog preferences page, found under Window
Preferences
Web and

XML
XML Catalog. While this preferences page is a good way for users to

650 CHAPTER 15 • Customizing Resource Resolution

Contributing Resources to the XML Catalog 651

Figure 15.2 Add XML Catalog Entry

Adding a Single Resource to the XML Catalog

As you saw earlier in Example 15.1, the J2EE deployment descriptor for a J2EE

1.4 application specifies the following location for its grammar:

http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd

Open this location in your Web browser. You will see that this location is

that of the J2EE schema. It is this file that you want to bundle with WTP.

The J2EE schema contains license terms in a documentation block at the top.

These are the terms that restrict WTP from bundling this schema. As long as you

accept the terms (perhaps schools should start teaching software developers

licensing law, as we frequently seem to be in positions that require us to under￾stand licensing terms), download the schema and save it in your plug-in in a

folder named j2eeschemas.

customize their workspace, it still requires user interaction and therefore will not

completely solve your problem. To bundle the J2EE schemas with WTP, you will

need to contribute them to the XML catalog using the XML catalog’s defined

extension point.

With the J2EE schema stored locally in your plug-in, you are ready to con￾tribute it to the XML catalog. Open your plug-in manifest editor and change to

the Dependencies tab. Add a dependency on

org.eclipse.wst.xml.core

The XML core plug-in contains non-UI XML functionality, including the

non-UI components of the XML catalog.

Next change to the Extensions tab. The XML catalog defines the following

extension point that allows you to add your own entries to the catalog:

org.eclipse.wst.xml.core.catalogContributions

Add a new catalogContributions extension. Give your new extension the id

j2eecatalog and the name J2EE Catalog. This extension will house all of your

contributions to the XML catalog.

Right click on the XML catalog extension and select New

catalogContribution. This extension element allows you to specify multiple cata￾log contributions, but for now you will only specify one.

Right click on the new catalogContribution and select New
system. This will

create a new entry in the XML catalog that specifies system identifier as the key.

Set the systemId to the location of the schema specified in the J2EE deployment

descriptor:

http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd

Set the uri, which specifies the location of the schema that you want to use,

to the relative location of the schema in your plug-in, namely

j2eeschemas/web-app_2_4.xsd

(You can also click Browse to select the location.) The effect of adding this entry

to the XML catalog is that when the J2EE schema location is requested, it will

return the local location of the schema from your plug-in. Save your plug-in

manifest. Change to the plugin.xml source view and view the extension declara￾tion (see Example 15.4).

Example 15.4 Listing of Catalog Extension

<extension

id="org.eclipsewtp.resourceresolution.j2eecatalog"

name="J2EE Catalog"

point="org.eclipse.wst.xml.core.catalogContributions">

<catalogContribution>

<system

systemId="http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"

uri="j2eeschemas/web-app_2_4.xsd"/>

</catalogContribution>

</extension>

652 CHAPTER 15 • Customizing Resource Resolution

Time to try out your changes. Launch a runtime workspace. When the work￾space is open, navigate to the XML catalog preference page. The J2EE schema

should now be listed in the catalog (see Figure 15.3). So far, so good.

Contributing Resources to the XML Catalog 653

Next create a new dynamic Web project. You can name the project anything

you like. Accept all the default settings and click Finish in the New Dynamic Web

Project wizard. The license dialog does not appear (good) and your new project

shows an error (bad). What went wrong? The error has occurred because the

J2EE schema is not a stand-alone schema. It requires other schemas that cannot

be resolved by the validator now that the schema is included in the XML catalog.

In the next section you will add the rest of the J2EE schemas to the XML catalog.

Figure 15.3 J2EE Schema Entry Added to XML Catalog

Tip: In this section you added a location for a schema system identifier to the XML

catalog. There is only one step you need to change in order to add a catalog entry

specifying a location for a schema’s public identifier (its namespace). Simply use the

public element instead of the system element and the publicId attribute instead

of the systemId attribute as follows:

Adding a Catalog of Resources to the XML Catalog

The method of adding an entry to the XML catalog that you used in the previous

section can be used to add many entries to the catalog. For each entry you simply

provide a new extension element of the appropriate type. So, you can use this

method to add the rest of the J2EE schemas and DTDs to the XML catalog.

The method for adding individual resources to the XML catalog works well

in many situations. However, one notable limitation is that it restricts the catalog

you create to Eclipse. This restricts who you can share your catalog with and

how others can make use of it.

WTP is not the only project that has an XML catalog implementation. This

type of facility is fairly common in tools that handle XML artifacts. To facilitate

sharing of catalogs among various tools, the OASIS standards body created an

XML catalog standard [XMLCatalogs], which specifies how to define an XML

catalog representation in an XML file. (See Example 15.5 for an example.) This

standard allows you to create XML catalogs that can be used in any tool that

supports the OASIS standard. As you’ve probably guessed by now, WTP sup￾ports the OASIS standard.

Example 15.5 Listing of OASIS XML Catalog File

<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">

<system uri="web-app_2_4.xsd"

systemId="http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd"/>

<system uri="j2ee_1_4.xsd"

systemId="j2ee_1_4.xsd"/>

<system uri="jsp_2_0.xsd"

systemId="jsp_2_0.xsd"/>

<system uri="j2ee_web_services_client_1_1.xsd"

systemId=

"http://www.ibm.com/webservices/xsd/j2ee_web_services_client_1_1.xsd"/>

<public uri="web-app_2_3.dtd”

publicId="-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"/>

<public uri="web-app_2_2.dtd"

publicId="-//Sun Microsystems, Inc.//DTD Web Application 2.2//EN"/>

</catalog>

654 CHAPTER 15 • Customizing Resource Resolution

<public

publicId="http://java.sun.com/xml/ns/j2ee"

uri="j2eeschemas/web-app_2_4.xsd"/>

You can also add entries to the catalog for DTD public and system identifiers using

the same method used for a schema by replacing the values of the publicId and

systemId attributes with DTD public and system identifiers.

For your J2EE catalog to be reusable within your organization, you will

create the OASIS XML catalog shown in Example 15.5 and contribute it to the

WTP XML catalog.

Before you create your J2EE OASIS XML catalog, you need to download the

rest of the J2EE schemas and DTDs. The J2EE 1.4 schemas are listed at

http://java.sun.com/xml/ns/j2ee/

You’ve already downloaded web-app_2_4.xsd, and

http://www.w3.org/2001/xml.xsd

is already bundled with WTP. The rest of the schemas that you need for a

J2EE 1.4 Web application are jsp_2_0.xsd, j2ee_1_4.xsd, and

j2ee_web_services_client_1_1.xsd, which is listed as

http://www.ibm.com/webservices/xsd/j2ee_web_services_client_1_1.xsd

Download these schemas and place them in the j2eeschemas folder in your

plug-in.

Next you need the J2EE 1.3 DTD, web-app_2_3.dtd, which is available from

http://java.sun.com/dtd/

Download this file and place it in the j2eeschemas folder.

The last resource you need to obtain is the J2EE 1.2 DTD, web-app_2_2.dtd,

which is available from

http://java.sun.com/j2ee/dtds/

Download this file as well and place it in the j2eeschemas folder.

Contributing Resources to the XML Catalog 655

Note: The J2EE schema and DTD pages contain listings for many other schemas

besides those that you have downloaded. These other schemas and DTDs are used

for other parts of the J2EE specification and are not needed for your immediate pur￾pose, although depending on your use you may find it beneficial to place these in your

catalog as well.

Now that you have all of your required resources you can create your

OASIS XML catalog. Create a new XML file in the j2eeschemas folder named

j2eeschemacatalog.xml to hold your catalog entries. Add the entries in the cata￾log (see Example 15.5 previously). The OASIS XML catalog standard and the

WTP XML catalog extension point are very similar by design, so your OASIS