14 Registering DTDs and XSDs with OC4J

This chapter describes the process for registering new entities - specifically any vendor-specific DTDs and XSDs used to define the format of XML deployment descriptors - within OC4J, which is required if XML file validation will be performed. It contains the following topics:

• Why Do DTDs/XSDs Have to Be Registered?

• Registering a DTD or XSD

Why Do DTDs/XSDs Have to Be Registered?

OC4J provides the ability to validate XML deployment descriptors at the time the files are read. This feature is enabled by passing the -validateXML argument on the oc4j.jar command line at OC4J startup. See Chapter 4, "OC4J Runtime Configuration" for details on command-line options.

Validation requires that the DTD or XSD defining an XML document be registered with the OC4J server. If this entity is not registered, XML validation may not occur.

When an XML document is read, the parser passes one or more keys identifying the DTD or XSD declared in the document to an OC4J component known as the Entity Resolver. The Entity Resolver resolves the location of the registered entity and returns it to the parser, enabling the XML document to be validated.

Two types of keys are used to reference an entity: A public identifier and a system identifier, both of which are declared in the XML document. Consider the following declaration in orion-application.xml, which references the DTD used to define the file format:

<!DOCTYPE orion-application 
PUBLIC "-//Evermind//DTD J2EE Application runtime 1.2//EN"
"http://xmlns.oracle.com/ias/dtds/orion-application.dtd">

• The public identifier is the string "-//Evermind//DTD J2EE Application runtime 1.2//EN"

• The system identifier is the URL "http://xmlns.oracle.com/ias/dtds/orion-application.dtd"

To enable the Entity Resolver to locate the entity, one or both of these identifiers must be registered with OC4J through entries in the entity-resolver-config.xml file. The entity's location must also be specified in this file.

Note that by default, entity-resolver-config.xml already contains registration entries for the standard J2EE DTDs and XSDs, as well as for all OC4J-specific XSDs. As such, you are only required to add entries for non-J2EE or non-OC4J entities.

Registering a DTD or XSD

To register a DTD or XSD with OC4J, you must add it to the entity-resolver-config.xml file, which is located in the ORACLE_HOME/j2ee/home/config directory on the OC4J host machine.

Each entity is declared in an <entity> element, which includes the following subelements:

• <description>: Contains an optional description of the entity.

• <public-id>: Contains the entity's public identifier.

• <system-id>: Contains the entity's system identifier.

  Either <public-id> or <system-id> must be specified; however, you are not required to specify both.

• <location>: Points to the entity's location. The location can be either the fully qualified path to the entity or a URL that can be resolved locally.

The following <entity> element will register acme-web.dtd with OC4J. Both the public and system identifiers, which are declared in the <!DOCTYPE> element within an XML document, are registered.

<entity>
  <description>acme-web-2_0.dtd</description>
  <public-id>-//Acme//Acme web Descriptor 2.0//EN</public-id>
  <system-id>http://xmlns.acme.com/dtd/acme-web-2_0.dtd</system-id>
  <location>META-INF/acme-web-2_0.dtd</location>
</entity>

The next example will register acme-application.xsd with OC4J. The system identifier is declared in either the xsi:schemaLocation or the xsi:noNamespaceSchemaLocation attributes of the root element within an XML document.

<entity>
  <description>acme-application-1_0.xsd</description>
  <public-id />
  <system-id>http://xmlns.acme.com/schema/acme-application-1_0.xsd</system-id>
  <location>META-INF/acme-application-1_0.xsd</location>
</entity>

Note: The OC4J server must be restarted after you make changes to entity-resolver-config.xml.