General |
top |
- What is XML Schema Infoset Model?
The
XML Schema Infoset Model is
a reference library for use with any code that examines, creates or modifies XML Schemas (standalone or as part of other artifacts,
such as XForms or WSDL documents). The library provides an API for manipulating the components of an XML Schema as described by the
W3C XML Schema specifications, as well as an API for manipulating the DOM-accessible representation of XML Schema as a series of XML
documents, and for keeping these representations in agreement as schemas are modified. The library includes services to serialize and
deserialize XML Schema documents, and to do integrity checking of schemas (for example, not using a maximum value for a simpleType
which is invalid considering the base type of that simpleType).
The model incorporates many of the ideas that several people at IBM had about an excellent API for schemas.
These ideas were shared with the W3C in February 2002, in a requirements document.
|
Download and Install |
top |
- How do I install XSD Infoset Model?
Download the version of XSD that matches your installation of
Eclipse. Exit Eclipse, and unzip into the eclipse directory.
- What should my Java CLASSPATH include, in order to use the library?
The classpath should be:
- plugins/org.apache.xerces_4.0.7/xmlParserAPIs.jar;
- plugins/org.apache.xerces_4.0.7/xercesImpl.jar;
- plugins/org.eclipse.emf.common_1.0.2/runtime/common.jar;
- plugins/org.eclipse.emf.ecore_1.0.2/runtime/ecore.jar;
- plugins/org.eclipse.xsd_1.0.2/runtime/xsd.jar;
- plugins/org.eclipse.xsd_1.0.2/runtime/xsd.resource.jar; (needed at runtime, not compile at time)
- yourcode.jar
Note that this version requires the use of Xerces-J 2.0.2 (or XML4J 4.0.7).
Other versions of Xerces-J may not work properly.
- What steps should I take to install the source code in one Eclipse project,
and to identify another project with my own code as dependent upon and using this library?
To install the source code in an Eclipse new project, follow these steps :
-
unzip org.eclipse.xsd.zip
in <XSD_HOME> directory
- create a new Eclipse project and import into it the content of <XSD_HOME>/plugins/org.eclipse.xsd
- set the directory containing the source of the new project to "src" (this directory was imported in the previous step)
- add the following locations to the classspath:
- <ECL_HOME>/plugins/org.apache.xerces_4.0.7/xercesImpl.jar;
- <ECL_HOME>/plugins/org.apache.xerces_4.0.7/xmlParserAPIs.jar;
- <XSD_HOME>/plugins/org.eclipse.emf.ecore_1.0.2/runtime/ecore.jar;
- <XSD_HOME>/plugins/org.eclipse.emf.common_1.0.2/runtime/common.jar;
<ECL_HOME> is the directory where ECL has been installed and <XSD_HOME> is the directory
where xsd.zip has been unzipped.
To identify another project with your own code as dependent upon and using this library, follow these steps :
- make sure that you have created a new project containing the code of this library as indicated previously;
- right click on the project folder which should use this library, click on "properties" popup menu item
- then, in the java Build Path section, go to the Project pane and check the project you previously created for this library.
|
Capabilities |
top |
- Can this library be used outside of
the Eclipse environment?
Yes, it can be used within Eclipse and outside of Eclipse.
Please note that when running outside Eclipse,
you need to include on your classpath this additional jar:
plugins/org.eclipse.xsd_1.0.2/runtime/xsd.resources.jar
- What version of W3C XML Schema is accepted as input?
The version specified on May 2, 2001 as a W3C Recommendation.
This version is described in XML Schema Part 0: Primer,
XML Schema Part 1: Structures,
and XML Schema Part 2: Datatypes.
- Does this library allow me to supply an instance document and have it validated
against the schema?
No. Validating parsers, such as Xerces, should be used for this function.
- Is there a function to inquire "Is this parsed or constructed schema completely correct?"
You can call
validate
on a schema and check whether there are any
diagnostics.
The diagnostics may include warnings or informational messages, in addition to error messages.
|
Compatibility |
top |
- What version(s) of Eclipse does this code work on?
Eclipse 2.1 (and 2.0.x)
|
Error Handling |
top |
- What happens if I pass a DOM which claims to be the XML representation of a Schema, but
there are errors in the attribute values?
The schema can be validated to diagnose all such errors.
See the capabilities.
|
How To Learn |
top |
- Are there sample Java methods that show how to use the API?
Sample code that includes links back to the javadoc is at:
XSDPrototypicalSchema.html.
Examples of convenience functions also illustrate the use of the bare API.
Those example convenience functions are in the source code. Info about them is located at
XSDSchemaBuildingTools.html
and
XSDSchemaQueryTools.html.
|
Miscellaneous |
top |
- Is there a way to have schema documents which
reference other schema documents through <include> <import> or <redefine>
be fetched from locations other than those given in the schemaLocation attribute?
Yes, you can use a ResourceSet's URIConverter's
URI map
to map logical URIs to physical URIs.
You can see an example of that code in XSDProtocotypicalSchema
traceLoading().
- When modification are made to a schema document
which was used by another schema document (which has been loaded by this library),
will my code need to explicitly make the corresponding modifications to the using schema document?
Yes.
- How does the model choose what prefix to use in QNAMEs for a namespace URI in serializing the schema,
when more than one prefix has been associated with that namespace?
One of the prefixes, or the no-prefix, will be chosen, and used consistently whenever
an XML representation of schema in the form of a DOM is requested.
This version of the code does not allow you to select which one will be chosen.
- Does the o1.equals(o2) method
determine "semantic equivalence" between two schema components?
This version of the code returns true if o1 and o2 are the same object,
otherwise it returns false.
- What happens if I add a schema component to schema2 that I had
previously added to schema1?
It is removed from schema1.
This package maintains referential integrity for black diamond relations (in the UML), i.e., containment relations.
When you add/set to a black diamond relation, the
object will be effectively removed from the current black diamond relation and is then added/set to the new relation.
- ComplexTypes and SimpleTypes only have at most 1 annotation. Why is there XSDTypeDefinition.getAnnotations() in addition to getAnnotation().
What is getAnnotations() used for?
There can be at most one annotation in the element information item in the XML Representation of schema which is a
<simpleType> or <complexType>.
But there can also be an annotation in the <restriction>, <extension>, <list>, <union> (getDerivationAnnotation),
as well as one in
the <simpleContent>, <complexContent> (getContentAnnotation) element information items that are part of (children of) the
simpleType or complexType element information item.
The list returned by getAnnotations() is the list of all these annotations.
- If I used one of the getEffectivePROPERTY() methods with a simpleType of the LIST or UNION type,
would any of the facet information from the itemType (in the case of List) or the memberTypes (in
the case of union) be used to adjust or supplement the values returned (as happens
with a simpleType which is atomic and derived by restriction from another type)?
No. We follow the concepts of effective properties from the W3C Schema specifications, which
do not cause facets of the memberTypes or item types to be used in the case of UNION or LIST.
- What can cause some of the resources in a resource set, which correspond
to schema documents referenced by <include> <import> or <redefine>, to return null from
(XSDResourceImpl)resource.getSchema() ?
This could be seen if you iterate through the resource in a ResourceSet, for example:
for (Iterator resources = resourceSet.getResources().iterator(); resources.hasNext();)
{ Resource resource = (Resource)resources.next(); /* Now use getSchema() */ }
If the <include> <import> or <redefine> contained a schemaLocation which has
a relative file path, the library will not resolve it, and this can be a symptom.
To get around this problem, have code which is guaranteed to turn the URI into an absolute
URI. For example:
File file = new File(schemaURL);
if (file.isFile()) {
schemaURL = URI.createFileURI(file.getCanonicalFile().toString()).toString();
}
- How is a declaration of an attribute or element that specifies anySimpleType
processed?
Following the clarifications to the spec, it is permissible to use anySimpleType in user schemas.
However, it is an error to extend or restrict this type except in the schema for schemas.
Note that an element declaration with an anyType will resolve its type to the complex version of "anyType" and an
attribute declaration with an anyType will resolve its type to the simple version of "anyType";
an element's type may be simple or complex, but an attribute's type must be simple.
- When will getElement()
return null when used against a component?
If the component you have has been synthesized, getElement() will return null.
For example, if you have selected the effective pattern facet, the model synthesized
that facet from the zero or more concrete pattern facets. Another effective facet
that comes from zero to an unlimited number of concrete facets is the enumeration facet.
If an XSDComplexTypeDefinition exists that extends another one, normally a synthesized
XSDModelGroup is produced, containing one or more synthesized
XSDParticle objects;
getElement() against those components would also return null.
|
Programming Tricks |
top |
- To obtain a component of a schema by name, or find out such a component does
not exist in the schema, what sequence of code should be used?
The resolveXXXDeclaration and resolveXXXDefinition methods declared in Interface
org.eclipse.xsd.XSDConcreteComponent allow lookup of components that have names.
Note that these methods always return something.
If your schema does not have the component you are looking for, the returned value will be a newly manufactured reference to it.
Here is an example method to return the component or return null if it was not in the schema,
in this case for an Attribute Declaration with a particular name:
/**
return the XSDAttributeDeclaration of a given namespace and name defined in a given schema
or a schema it includes, redefines or imports
*/
static XSDAttributeDeclaration
getAttributeDeclaration(XSDSchema schema, String namespace, String name) {
XSDAttributeDeclaration ret=schema.resolveAttributeDeclaration(namespace,name);
if (ret.getContainer() == null()) {
return null;
} else {
return ret;
}
}
- How can the attribute maxOccurs="unbounded" be set on a particle?
Use XSDParticle.setMaxOccurs(-1) to set an unbounded value for maxOccurs.
XSDParticle.getMaxOccurs will return -1 if a particle has an unbounded value for maxOccurs.
- When passed an object of type XSDSchema, what method tells me if it was
parsed from a Resource?
xsdSchema.eResource() returns a Resource, if one is associated, or returns nill.
The Resource returned has methods such as getURI().
- When passed an object of type XSDSchema, what method permits me to alter the Resource
in which it will be serialized?
r = xsdSchema.eResource() returns the Resource associated with an XSDSchema. You may invoke
r.setURI(uri) if you wish the schema to be saved in the future to another location.
- How do I remove a component from the Schema?
There is generic support for remove in EMF:
EcoreUtil.remove
The removed component will look like an unresolved reference to any components that still reference it.
- If I want the library to parse a Schema from a file which does not have the
extension .xsd,
or serialize a Schema to a file which does not have the extension .xsd,
what do I do?
As part of your initialization, for each extension that will contain schemas (shown as foo in this
example), you should call
org.eclipse.emf.resource.Resource.Factory.Registry.INSTANCE.registerExtension("foo",
new XSDResourceFactoryImpl());
- Is there a function to inquire "Did this parsed schema
have unresolved <include> <import> or <redefine> directives?"
You can write code like this:
if (xsdSchema.getAllDiagnostics().isEmpty()) { xsdSchema.validate(); }
if (xsdSchema.getAllDiagnostics().isEmpty()) { /* No Unresolved directives */ }
else { */ Unresolved directives or other problems */ }
- Is there a way to determine if a string represents a value that
a particular simpleType would
consider valid?
Yes. The call
yourSimpleTypeDefinition.isValidLiteral("a-particular-string")
will give you the boolean answer.
- When I used the method type.getBaseTypeDefinition(), how do I know when I've
reached "the top" -- something like anyType?
For simpleTypes, you would write:
yourStopVariable = yourSchema.getSchemaForSchema().resolveSimpleTypeDefinition("anyType");
/* as you loop through from one type definition to another, via getBaseTypeDefinition()
you compare it to yourStopVariable */
For complexTypes, you would write:
yourStopVariable = yourSchema.getSchemaForSchema().resolveComplexTypeDefinition("anyType");
/* as you loop through from one type definition to another, via getBaseTypeDefinition()
you compare it to yourStopVariable */
If you are not sure if your time is simple or complex, you could write:
yourStopVariable = yourSchema.getSchemaForSchema().resolveTypeDefinition("anyType");
There are recognizers of the special types in XSDConstants:
XSDConstants.isURType
XSDConstants.isAnyType
XSDConstants.isAnySimpleType
Because td = resolveTypeDefinition(String nsuri, String name) may return
an unresolved instance, which is synthesized to hold the namespace and name, if an existing instance cannot be found,
what method can be called to tell whether the resulting type definition is synthesized or
whether it comes from an existing instance?
XSDConcreteComponent.getContainer() will yield null for td if resolveTypeDefinition returned a synthesized type definition.
|