FAQ - Frequently Asked Questions

If you have additional questions that you would like to see answered in future versions of this FAQ or in the Javadoc, please e-mail them to rschloss@us.ibm.com.


1. Can this library be used within Eclipse-based tools, and outside of the Eclipse environment?  GO

2. 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?  GO

3. What version of W3C XML Schema is accepted as input?  GO

4. Are there sample Java methods that show how to use the API?  GO

5. Where do I download the latest code?  GO

6. Does this library allow me to supply an instance document and have it validated against the schema?  GO

7. What should my Java CLASSPATH include, in order to use the library?  GO

8. What version(s) of Eclipse does this code work on?  GO

9. What version(s) of WebSphere Studio Workbench does this code work on?  GO

10. What version(s) of WebSphere Studio Application Developer does this code work on?  GO

11. 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?  GO

12. What steps should I take to install the source code in one WSAD 4.0 project, and to identify another project with my own code as dependent upon and using this library?  GO

13. When I report a bug, where do I find the exact version number of the library?  GO

14. 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?  GO

15. What facilities of the schema language are not currently supported?  GO

16. How can the attribute maxOccurs="unbounded" be set on a particle?  GO

17. Why does this library use the EMF runtime under the covers?  GO

18. How do I start to learn how to use this? Are any examples available?  GO

19. When passed an object of type XSDSchema, what method tells me if it was parsed from a Resource?  GO

20. When passed an object of type XSDSchema, what method permits me to alter the Resource in which it will be serialized?  GO

21. Where are the JAR files I need on my classpath?  GO

22. How do I remove a component from the Schema completely -- not leaving any dangling references?  GO

23. 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?  GO

24. Does the o1.equals(o2) method determine "semantic equivalence" between two schema components?  GO

25. 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?  GO

26. 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?  GO

27. Is there a function to inquire "Is this parsed or constructed schema completely correct?"  GO

28. Is there a function to inquire "Did this parsed schema have unresolved <include> <import> or <redefine> directives?"  GO

29. What happens if I add a schema component to schema2 that I had previously added to schema1?  GO

30. Is there a way to determine if a string represents a value that a particular simpleType would consider valid?  GO

31. What version of the Java Runtime Environment is this library tested on?  GO

32. ComplexTypes and SimpleTypes only have at most 1 annotation. Why is there XSDTypeDefinition.getAnnotations() in addition to getAnnotation(). What is getAnnotations() used for?  GO

33. What mailing list should be used to discuss the use of this feature?  GO


1. Can this library be used within Eclipse-based tools, and 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 set a system property named VABASE, for example:

java -DVABASE=directoryWhichContainsASubdirectoryNamedPlugins ....

and inside directory Plugins must exist a directory com.ibm.etools.xsd.wswb_1.0.0, and inside directory com.ibm.etools.xsd.wswb_1.0.0 must exist a directory cache.

2. 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 associate a context with a resourceSet, and a mapping registry with that context. Here is an example of that code:

com.ibm.etools.emf.Init.init();
com.ibm.etools.emf.resource.UriMappingRegister.registerMapping(
 "textThatWouldAppearInSchemaLocation", "fileNameToUseInstead.xsd");
com.ibm.etools.emf.resource.UriMappingRegister.registerMapping(
 "text2ThatWouldAppearInSchemaLocation", "fileName2ToUseInstead.xsd");
com.ibm.etools.emf.resource.ContextResourceFactoryRegister crfr = 
 new com.ibm.etools.emf.resource.ContextResourceFactoryRegister();
com.ibm.etools.emf.resource.Context context = 
 crfr.getContextFactory().makeContext();
com.ibm.etools.emf.resource.ResourceSet set = 
 crfr.getResourceSetFactory().makeResourceSet();
com.ibm.etools.emf.resource.URIConverter converter = 
 com.ibm.etools.emf.resource.URIConverterRegister.getURIConverter();
context.setURIConverter(converter);
set.setContext(context);

3. 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.

4. 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.

5. Where do I download the latest code?

Partnerworld for Developers

6. 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.

7. What should my Java CLASSPATH look like, in order to use the library?

  • plugins/org.eclipse.core.boot_2.0.0/boot.jar;
  • plugins/org.eclipse.core.runtime_2.0.0/runtime.jar;
  • plugins/org.apache.xerces_4.0.3/xmlParserAPIs.jar;
  • plugins/org.apache.xerces_4.0.3/xercesImpl.jar;
  • plugins/org.eclipse.core.resources_2.0.0/resources.jar;
  • plugins/com.ibm.etools.emf.wswb_50.020528.0/emf.jar;
  • plugins/com.ibm.etools.xsd.wswb_1.0.0/xsd.jar;
  • yourcode.jar
Note that this version requires the use of Xerces-J 2.0.3 (or XML4J 4.0.3). No other version of Xerces-J works properly.

8. What version(s) of Eclipse does this code work on?

9. What version(s) of WebSphere Studio Workbench does this code work on?

10. What version(s) of WebSphere Studio Application Developer does this code work on?

  • You should not replace com.ibm.etools.emf or com.ibm.etools.xsd in the plugins directory of WSAD 4.0.3 . You may import this code into a project you create in your WSAD workspace.

11. 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.

12. What steps should I take to install the source code in one WSAD 4.0 project, and to identify another project with my own code as dependent upon and using this library?

To install the source code in a WSAD 4.0 new project, follow these steps :
  • unzip xsdsrc.jar in <XSD_HOME> directory
  • create a new WSAD project and import into it the content of <XSD_HOME>/plugins/com.ibm.etools.xsd.wswb_1.0.0
  • 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 :
    • <WSAD_HOME>/plugins/org.eclipse.core.boot_2.0.0/boot.jar;
    • <WSAD_HOME>/plugins/org.eclipse.core.runtime_2.0.0/runtime.jar;
    • <WSAD_HOME>/plugins/org.apache.xerces_4.0.3/xercesImpl.jar;
    • <WSAD_HOME>/plugins/org.apache.xerces_4.0.3/xmlParserAPIs.jar;
    • <WSAD_HOME>/plugins/org.eclipse.core.resources_2.0.0/resources.jar;
    • <XSD_HOME>/plugins/com.ibm.etools.emf.wswb_50.020528.0/emf.jar;
    <WSAD_HOME> is the directory where WSAD has been installed and <XSD_HOME> is the directory where the zip containing this FAQ 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 libary, 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.

13. When I report a bug, where do I find the exact version number of the library?

Look in plugin.xml in the directory that contains plugins/com.ibm.etools.xsd.wswb_1.0.0/xsd.jar at the value of the attribute "build-level" on the "plugin" element.

14. 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 com.ibm.etools.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.isAttributeDeclarationReference()) {
		return null;
	} else {
	return ret;
	}
}

15. What facilities of the Schema language are not currently supported?

Primitive datatypes gYearMonth, gYear, gMonthDay, gDay, gMonth are not supported in this release.

16. 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.

17. Why does this library use the EMF runtime under the covers?

This library was developed with some IBM-unique tools that emits Java code scaffolding which manages relationships between objects based on how they are related in the UML Logical Class Diagrams. The emitted code makes use of relationship- and resource-management services in the EMF runtime. It supports a sophisticated notification framework that allows programs to register as listeners for various mutation events on schemas. IBM is in the process of submitting to the OMG, revisions of models and meta-models for the MOF2, XMI for MOF2 and UML2 specifications, which have been influenced by EMF in general and the design/implementation of the Java interfaces to manipulate the XML Schema Info set Model in particular. EMF is an acronym for E-Modeling Framework.

18. How do I start to learn how to use this? Are any examples available?

Class com.ibm.etools.xsd.util.XSDPrototypicalSchema contains several methods that show the code to create a schema, to read in a schema document, and so on.

19. When passed an object of type XSDSchema, what method tells me if it was parsed from a Resource?

xsdSchema.refResource() returns a Resource, if one is associated, or returns nill. The Resource returned has methods such as getURI().

20. When passed an object of type XSDSchema, what method permits me to alter the Resource in which it will be serialized?

r = xsdSchema.refResource() 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.

21. Where are the JAR files I need on my classpath?

They can be found in any WSWB_2.0*.zip deliverable. They are:
plugins/org.eclipse.core.boot_2.0.0/boot.jar
plugins/org.eclipse.core.runtime_2.0.0/runtime.jar
plugins/org.apache.xerces_4.0.3/xercesImpl.jar
plugins/org.apache.xerces_4.0.3/xmlParserAPIs.jar
plugins/org.eclipse.core.resources_2.0.0/resources.jar

22. How do I remove a component from the Schema completely -- not leaving any dangling references?

For element declarations, attribute declarations, named model groups definitions, and attribute group definitions, you would do something like this:

    XSDElementDeclaration xsdElementDeclaration = 
      yourSchema.resolveElementDeclaration("elementName");
    XSDSchema xsdSchema = xsdElementDeclaration.getSchema();
    if (xsdSchema != null)
    {
      xsdSchema.getContents().remove(xsdElementDeclaration)
    }

So you get the resolved component, make sure it's in a schema to ensure that it's not an unresolved component, and then you remove it from the schema contents.

For type definitions, this approach is appropriate:

    XSDTypeDefinition xsdTypeDefinition = 
      yourSchema.resolveTypeDefinition("typeName");
    XSDConcreteComponent container = xsdTypeDefinition.getContainer();
    if (container instanceof XSDSchema)
    {
      ((XSDSchema)container).getContents().remove(xsdTypeDefinition)
    }
    else if (container instanceof XSDRedefine)
    {
      ((XSDRedefine)container).getContents().remove(xsdTypeDefinition)
    }

So you get the resolved component, get its container, figure out what type of container it is, and then you remove it from the appropriate relation of that container. Note that type definitions can be contained by redefines as well as directly by the schema.

23. 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.

24. 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.

25. 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?

This version of the code will not necessary give an exception when trying to build abstract components from such a DOM, but the resulting XSDSchema may not be usable and may not be serializable. We hope to have a better solution in a later version of the library.

26. 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
com.ibm.etools.emf.resource.ResourceFactoryRegister.registerExtension("foo", 
  new XSDResourceFactoryImpl());

27. Is there a function to inquire "Is this parsed or constructed schema completely correct?"

No.

28. 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 */ }

29. 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.

30. 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.

31. What version of the Java Runtime Environment is this library tested on?

JRE 1.3

32. 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.

33. What mailing list should be used to discuss the use of this feature?

For the month of June 2002, we will monitor xmlschema-dev@w3.org .


Last date the FAQ was updated: June 14, 2002 12:10 EDT