jakartaee / jaxb-api

Jakarta XML Binding project

The Jakarta XML Binding provides an API and tools that automate the mapping between XML documents and Java objects.

License

• Most of the Jakarta XML Binding project source code is licensed under the Eclipse Distribution License (EDL) v1.0.; see the license information at the top of each source file.
• The source code for the Jakarta XML Binding Specification project is licensed under the Eclipse Public License (EPL) v2.0 and GNU General Public License (GPL) v2 with Classpath Exception; again, the license is in each source file.
• The binary jar files published to the Maven repository are licensed under the same licenses as the corresponding source code; see the file META-INF/LICENSE.txt in each jar file.

You’ll find the text of the licenses in the workspace in various LICENSE.txt or LICENSE.md files. Don’t let the presence of these license files in the workspace confuse you into thinking that they apply to all files in the workspace.

You should always read the license file included with every download, and read the license text included in every source file.

Contributing

We use contribution policy, which means we can only accept contributions under the terms of Eclipse Contributor Agreement.

jaxb-api's Issues

mapping of property/field to xs:sequence - default order

The JSR 222 EG already agreed that a mapping rule that maps the
Javabean like properties and fields within a class to a xs:sequence
compositor should be supported. However, the Javabean properties and
fields within a class are unordered. So should there be default order
specified ?

One suggestion was to use alphabetical order as default order.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

mapping class -> complex type with simple content

Mapping a class to a complex type definition with simple content
was suggested useful. From the minutes of April 24, 2004 conference call

https://www.dev.java.net/files/documents/919/3142/feb-24-2004.txt

bullet item 2.

----- Start: Extract from minutes -----

2. Mapping class to a complex type definition

a. content type

• content type should read: empty, simple content, or a pair of
  content model, and one of mixed or element only.
• missing simpleContent; might be useful to allow this with a
  customization.

----- End: Extract from minutes -----
This is not noted in the minutes. However, the suggestion of mapping
to simple content was made by Ed Merks.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

Unmarshaller StAX API clarification

The new StAX APIs on javax.xml.bind.Unmarshaller need to specify that
START_DOCUMENT is a legal state for the XMLStreamReader or XMLEventReader
passed into the unmarshal() method.

The javadoc currently says that the methods throw IllegalStateException
for anything other than START_ELEMENT.

Environment

Operating System: All
Platform: All
URL: https://jsr222.dev.java.net/nonav/api/javax/xml/bind/Unmarshaller.html

Affected Versions

[2.0 v0.4]

Using XSD and JAXB annotations for Java -> XSD customization

The customizations are listed here can be customized using the
customization facility defined in JAXB 1.0 using the third approach in
Section "8.15.1, Issue: Metdata - Locations and tradeoffs" on page 188
of the draft specification:

https://jsr222.dev.java.net/files/documents/919/3577/jaxb20-106.pdf

i.e. the XML schema can be generated once. Then the customization can
be done on the generated schema. The customized schema is then never
regenerated but only mapped back to class. This would eliminate the
need for defining customizations using JSR175 annotations listed
here using the Java annotations.

• default values for attributes and elements with simple type declarations.
• mapping property/field to a required attribute
• mapping property/field to a fixed attribute
• ordering the elements - to which properties/fields are mapped; since
  the ordering can be changed after XML schema has been generated.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

XmlElement.isNillable name inconsistency

It is customary for annotation parameters not to accompany a verb.
For example, you don't name it "getValue", but you name it "value".
You don't name it "getName", but you name it "name".

Most of the JAXB annotations follow this convention correctly,
yet "isNillable" is not. This should be renamed to "nillable" for
consistency.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 v0.4]

Java to XML Identifier mapping algorithm needs to be defined

The following issue was raised by Scott Ziegler

There are a host of characters that are legal in a
java identifier that are not legal as xml names. I think JAXB will need
a java -> xml name mapping algorithm. Here's a little program to print
them (requires xerces):

import org.apache.xerces.util.XMLChar;

public class NameTest
{
public static void main(String[] args)
{
for (char c = 0; c < Character.MAX_VALUE; c++) {
if (Character.isJavaIdentifierPart(c)) {
if (!XMLChar.isName(c))

{ System.out.println("CHAR:\t" + (int)c); }

}
}
}
}

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

mapping of interface to XML schema

The mapping of interfaces to an XML schema construct was only briefly
mentioned in the conference call both further discussion and
resolution are pending.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

Unmarshaller.unmarshal method that takes java.io.Reader

XML can be read from java.io.Reader, and often people do that, yet the
javax.xml.bind.Unmarshaller interface doesn't have a version that takes
java.io.Reader.

This is a strange omission given that the Marshaller has a version of the
marshal method that takes java.io.Writer.

Currently the user can work around this problem by:

unmarshaller.unmarshal(new StreamSource(reader));

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 v0.4]

XMLGregorianCalendar missing a schema-aware comparison function

Submitted by David Bau, entered by Joe Fialli

There is no schema-aware comparison function on the
XmlGregorianCalendar type. This is useful for validation, but it requires a
four-state (not a three-state) return value, because there is a "not equal
to" result defined by schema.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

XMLGregorianCalendar years & seconds precision

Submitted by David Bau, entered initially by Joe Fialli.

Concerning javax.xml.datatypes.XMLGregorianCalendar:

To permit correct behavior on validation tests, it is important that, like
Duration, the calendar type be able to handle large years and more than
three digits of fractional seconds; it would also be optimal if the number
of significant digits of seconds were remembered, so that dates can be
nicely round-tripped to XML. I recommend that this information be able to
be held by the XmlGregorianCalendar implmentation and accessible by its own
API, but truncated when queried by the ordinary Calendar API.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

mapping of property/field to xs:sequence - customization

The JSR 222 EG already agreed that a mapping rule that maps the
Javabean like properties and fields within a class to a xs:sequence
compositor should be supported.

Should a JSR175 annotation based customization be defined to allow the
customization of the order of elements within an xs:sequence
compositor. This is dependent upon the resolution to issue 14.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

Is Java source roundtripping (java->xsd->java) a requirement ?

This is an issue for a JAXRPC service client brought up in the JAXRPC
2.0 F2F.

The following text (reproduced here to avoid document chasing)
provides the background for this issue and and is taken from the
second bullet item in Section 9.1,�Requirements� in JAXRPC 1.1
specification:

https://jsr222.dev.java.net/files/documents/919/2643/jaxrpc-1_1-fr-spec.pdf

A service client environment should be capable of importing a WSDL
document and generating a Java based client side representation for a
service described in this document. A client side representation
includes classes Requirements generated based on the mapping of
the WSDL definitions to the corresponding Java representation.

ISSUE: [Issue is from JAXRPC 2.0 F2F March 11,12 F2F]. It was noted at
the JAXRPC 2.0 F2F that the classes generated from a WSDL document on
a JAXRPC service client should be similar not necessarily identical to
the JAXRPC service classes from which the WSDL document was generated
on the server. The example discussed was that Date can be mapped to
xsd:date in the WSDL document generated when a JAXRPC service is
exported. But xsd:date may be mapped to Calendar in the generated
classes on the JAXRPC service client. This is a JAXB 2.0 issue since
JAXB 2.0 specifies the mapping rules used in the generation of the
section.

While roundtripping may be desirable, since JAXRPC service client’s view is the
WSDL document - not the JAXRPC service classes - a requirement for rountripping
is not totally clear. JAXB 2.0 can assist in the roundtripping by generating schema
annotations on the XML schema constructs generated in the
section.

NOTE: Roundtripping of source for Schema -> Java -> Schema case is not
a requirement.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

mapping XML schema for containment vs reference

Issue 22: mapping : Containment vs. reference

The following two approaches have been discussed in the expert group
prior to the F2F.

1. JAXB 2.0 provides mechanisms which can be used to customize the
generated XML schema to allow a reference to an object to be
marshalled by containment or by reference.This approach has
issues - not user friendly (e.g. can result in for cycles), hard
to use etc. Nonetheless, this option does provide control to a
user for customizing the generated schema and was thought
worthwhile to explore this option further.

The discussion threads are here:

http://archives.java.sun.com/cgi-bin/wa?A2=ind0402&L=jsr-222-eg&X=12E27C5E49150B4D5C&[email protected]&P=3204

http://archives.java.sun.com/cgi-bin/wa?A2=ind0403&L=jsr-222-eg&X=12E27C5E49150B4D5C&[email protected]&P=728

2. JAXB 2.0 determines based on the object graph the marshalling of
an object by containment or reference. For example, the first time
an object is marshalled, it is marshalled by
containment. Subsequent references of object are marshalled by
reference. This would be enabled by generating an XML schema with
a xs:choice that includes both an id or a reference to an id
(defined elsewhere). See the thread

http://archives.java.sun.com/cgi-bin/wa?A2=ind0402&L=jsr-222-eg&X=12E27C5E49150B4D5C&[email protected]&P=3204

Additionally the following approach was suggested at the JAXB 2.0 F2F.

3. A third approach was suggested in JAXB 2.0 F2F by Steve
Brodsky. The discussion is in bullet 13 in the F2F minutes:

https://www.dev.java.net/files/documents/919/3776/f2f-minutes.txt

The summary of this approach is: XML instance could just list
every single object at the top-level and all the references can be
ID/IDREF (since Java does not distinguish between containment
vs. reference). The generated XML schema might not be useful or
meaningful in some cases. In such a case, Java classes have to be
customized to produce the desired XML schema i.e. use approach 1
noted in bullet item 1 above.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

Schema generation dies on subclasses of java.util.Date

When a subclass of java.util.Date has to be mapped to XML, apt dies in round 2
with the following error:

[apt] Problem encountered during annotation processing;
[apt] see stacktrace below for more information.
[apt] java.lang.ClassCastException:
com.sun.xml.bind.v2.model.impl.BuiltinLeafInfoImpl
[apt] at
com.sun.xml.bind.v2.model.impl.ClassInfoImpl.getBaseClass(ClassInfoImpl.java:170)
[apt] at
com.sun.xml.bind.v2.model.impl.ModelBuilder.getClassInfo(ModelBuilder.java:142)
[apt] at
com.sun.xml.bind.v2.model.impl.ModelBuilder.getTypeInfo(ModelBuilder.java:189)
[apt] at
com.sun.xml.bind.v2.model.impl.TypeRefImpl.calcRef(TypeRefImpl.java:56)
[apt] at
com.sun.xml.bind.v2.model.impl.TypeRefImpl.getTarget(TypeRefImpl.java:33)
[apt] at
com.sun.xml.bind.v2.model.impl.ElementPropertyInfoImpl$1.get(ElementPropertyInfoImpl.java:38)
[apt] at
com.sun.xml.bind.v2.model.impl.ElementPropertyInfoImpl$1.get(ElementPropertyInfoImpl.java:41)
[apt] at java.util.AbstractList$Itr.next(Unknown Source)
[apt] at
com.sun.xml.bind.v2.model.impl.ModelBuilder.getClassInfo(ModelBuilder.java:139)
[apt] at
com.sun.xml.bind.v2.model.impl.ModelBuilder.getTypeInfo(ModelBuilder.java:189)
[apt] at
com.sun.xml.bind.v2.model.impl.ModelBuilder.getTypeInfo(ModelBuilder.java:204)
[apt] at
com.sun.tools.xjc.api.impl.j2s.JavaCompilerImpl.bind(JavaCompilerImpl.java:54)
[apt] at
com.sun.tools.ws.processor.modeler.annotation.WebServiceAP.completeModel(WebServiceAP.java:395)
[apt] at
com.sun.tools.ws.processor.modeler.annotation.WebServiceAP.process(WebServiceAP.java:236)
[apt] at
com.sun.mirror.apt.AnnotationProcessors$CompositeAnnotationProcessor.process(AnnotationProcessors.java:60)
[apt] at com.sun.tools.apt.comp.Apt.main(Apt.java:450)
[apt] at
com.sun.tools.apt.main.JavaCompiler.compile(JavaCompiler.java:458)
[apt] at com.sun.tools.apt.main.Main.compile(Main.java:1075)
[apt] at com.sun.tools.apt.main.Main.compile(Main.java:938)
[apt] at com.sun.tools.apt.Main.processing(Main.java:95)
[apt] at com.sun.tools.apt.Main.process(Main.java:43)
[apt] at com.sun.tools.apt.Main.main(Main.java:34)

The following class definitions should reproduce the error:

========== test/DateTime.java ==========
package test;

import java.util.Date;

public class DateTime extends Date {
public DateTime() {}
}

========== test/Svc.java ==========
package test;

import javax.jws.*;

@webservice public class Svc {
@webmethod public DateTime getDateTime()

{ return null; }

}

Environment

Operating System: All
Platform: PC

Affected Versions

[2.0 EA1]

mapping - default mapping of class is incorrect

In the JAXB 2.0 ED 0.40, the default mapping of class is xs:all. It should be
xs:sequence; this has already been agreed to earlier in the JAXB 2.0 EG.
The specific error is:

Error: Section 8.8.1.1, "Synopsis" reads

public @interface XmlType {
String name();
String[] propOrder() default {}; ***** incorrect default *****
String targetNamespace() default "##default" ;
}

However it should read

public @interface XmlType {
String name();
String[] propOrder() default ""; ****** correct default ******
String targetNamespace() default "##default" ;

With the above change, the class would be mapped to xs:sequence
(see table, 8-5, "Mapping: Class body to Model Group Component").

Note: The above bug does not exist in the javadoc for
the javax.xml.bind.annotation.XmlType annotation.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 v0.4]

Schemas with deep nesting is more common than we thought

We've been seeing reports from users saying that they have to work with a schema
that has a very deep nested structure.

JAXB 1.0 produces the nested interfaces for such elements/types, and as a result
it produces names too long to be used. In fact, the complaints were that the
class file name becomes so long that it goes beyond the OS limit.

Currently, there's no workaround for this problem.
I wonder if the EG could consider this problem in JAXB 2.0.

Environment

Operating System: All
Platform: All

Affected Versions

[1.0]

mapping : external java->xsd binding customization file

An external java->xsd binding file may be needed to:

a. provide multiple ways to serialize/deserialize a single set of
classes by generating different XML schemas.

b. apply customizations to code that cannot be annotated using
JSR175 annotations (e.g. library).

The current proposal is described in note:

https://www.dev.java.net/files/documents/919/3959/jaxb20-note-0015.txt

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

define unmarshal behavior for invalid content

Submitted by David Bau, entered by Joe Fialli.

Request is to define unmarshal behavior of invalid content when unmarshalling
validation is disabled.

Here is the exact content that is being requested to be defined by the
specification.
Extracted from JAXB 1.0 Specification, Section 2.1.2 Binding Framework, Ph 3

"How a JAXB technology implementation handles unmarshalling of an invalid
document when validation is disabled is implementation-specific. The same holds
true for marshalling an invalid content tree. It is expected that once an
implementation is aware that it cannot unambiguously complete unmarshalling or
marshalling, it will terminate processing with an exception."

Environment

Operating System: All
Platform: All

Affected Versions

[1.0]

mapping : adapting Java structures to XML representation

Proposed by Dennis Sosonski

Dennis proposed an adapter approach for handling Java structures that
don't have a natural XML representation. This was originally proposed
in the context of HashMap but is not specific to mapping of HashMap.
See the email thread:

http://archives.java.sun.com/cgi-bin/wa?A2=ind0402&L=jsr-222-eg&F=&S=&X=78A3F110158D3BF325&[email protected]&P=173

This was also discussed briefly at the F2F and thought to be useful by
JAXB 2.0 EG members present and deserved further investigation. See
bullet item 11 in the F2F minutes:

https://jsr222.dev.java.net/files/documents/919/3776/f2f-minutes.txt

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

mapping collection : java.util.Set -> XSD construct

Issue raised by Ias.

java.util.Set is part of the Java Collection Framework; it
should be mapped to an XML schema construct.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

Retrofitting exception link mechanism of JAXBException

Since JAXB 2.0 is going to require J2SE 5.0, we should take this opportunity to
retrofit JAXBException's exception chaining mechanism into that of JDK 1.4.

Today, JAXBException has its own mechanism to link to another (wrapped) exception,
and it has its own code to print the information about this linked exception
in its printStackTrace method.

Starting from JDK 1.4, java.lang.Throwable has this exact feature. We can take
advantage of this by tweaking JAXBException.

The change would allow the stack trace to be printed in the same way as the rest
of exceptions. The printing method in JDK is also smarter than the one in
JAXBException.

When making this change, we have to be careful not to break the compatibility.
Fortunately, many of the core JDK exceptions
(such as java.lang.InvocationTargetException) went through this retrofitting
process, so we know how to do it right.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 v0.4]

DatatypeConverter / DatatypeConverterInterface are underspecified

It doesn't say what happens in case of an error. Does it throw an exception?
Does it just return null?

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 v0.4]

mapping class -> global elements with anonymous type

A mapping of a class to a global element with an anoymous type
was suggested on the expert group mail alias ( Subject header
Mapping of class to a global element with anonymous type").
Extract from the email alias:

This mapping rule will allow the binding to an element with an
anonymous complex type. For example, Section 1.2, "WSDL Document
Example" in WSDL 1.1 specification
http://www.w3.org/TR/wsdl#_wsdl

contains the following schema fragment

#### Environment Operating System: All Platform: All #### Affected Versions [2.0 draft]

mapping of java.lang.Object

I suggested the mapping of java.lang.Object to xs:anyType in the
context of type substitution. Keith Visco suggested that
java.lang.Object could also be mapped to xs:any.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

mapping class-> complex type with mixed content

Following extract is from the minutes of the Feb 24, 2004 EG
conference call:

b. support for mixed content

• not a lot of use cases for supporting mixed content
• one possibility is to introduce a customization to customize
  a String property to be text. I believe suggested by Keith
  Visco.
• issue: how to handle adjacent text strings
• another possibility: no support for mixed content; document
  produced by JAXB can be processed by an external tool such as
  XSLT.

So should customization of a mapping a Java class to mixed content be
supported ?

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

XMLGregorianCalendar needs a getXmlSchemaType() method

Submitted by David Bau, entered initially by Joe Fialli

There should be a method to say "which one of the XML Schema Date
types does this correspond to"? based on the set fields, e.g., have an
enumeration for gYear, gMonth, gMonthYear, as well as no-type, and then have
a getXmlSchemaType() method. What's the use case? We have some customers
with schemas where they have unions of various XML Schema Date types, and it
is very useful to know which member of the union they have.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

package to namespace: default mapping

Should a default mapping of a package to namespace URI be specified ?

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

JAXB doesn't support collection classes as top level objects

JAXB 2.0 has no provision of handling any collection class as a top-level
object. It can only handle them as properties of beans. To use jax-ws without
the need for wrapper classes for collections, jaxb needs to support this.

Scenario:
If you try to build a webservice with JAX-WS 2.0 and use a collection class in a
service method directly, the generated schema is useless.

Example:

@webservice
@SOAPBinding(style = Style.RPC)
public class CollectionAsParamTestService
{
public void testCollections(ArrayList stringList)
{

}
}

If I generate the wsdl and the corresponding schema with wsgen, the wsdl is
generated with the following message fragment:

So far so good. Now the generated schema:

<xs:schema version="1.0"
targetNamespace="http://impl.service.webservice.fss.portal.o2.com/"
xmlns:xs="http://www.w3.org/2001/XMLSchema">

<xs:complexType name="arrayList">
xs:complexContent
<xs:extension base="ns1:abstractList"
xmlns:ns1="http://impl.service.webservice.fss.portal.o2.com/">
xs:sequence/
</xs:extension>
</xs:complexContent>
</xs:complexType>

<xs:complexType name="abstractList" abstract="true">
xs:complexContent
<xs:extension base="ns2:abstractCollection"
xmlns:ns2="http://impl.service.webservice.fss.portal.o2.com/">
xs:sequence/
</xs:extension>
</xs:complexContent>
</xs:complexType>

<xs:complexType name="abstractCollection" abstract="true"/>
</xs:schema>

So the xsd:string is missing inside the xs:sequence from the service call.

See also https://jax-ws.dev.java.net/issues/show_bug.cgi?id=28

Environment

Operating System: All
Platform: All

Affected Versions

[2.0.2]

add XMLGregorianCalendar.add(Duration)

Add a method to javax.xml.datatype.XMLGregorianCalendar that adds a Duration to
XMLGregorianCalendar.

Duration.addTo(java.util.Calendar) and Duration.addTo(java.util.Date) already
provide
a means to add a duration to these object. Add the logical equivalent of adding
duration to XMLGregorianCalendar, XMLGregorianCalendar.addTo(Duration).

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

Marshaller StAX API's underspecified

The new StAX API's on javax.xml.bind.Marshaller are underspecified.

They need to explain when/if document level events are generated
on the XMLStreamWriter/XMLEventWriter.

Environment

Operating System: All
Platform: All
URL: https://jsr222.dev.java.net/nonav/api/javax/xml/bind/Marshaller.html

Affected Versions

[2.0 v0.4]

JAXBElement to implement equals and hashCode

Hi.

javax.xml.bind.JAXBElement currently does not override equals(...) and
hashCode() methods. Since this class is used to wrap "real" values, it is
desirable to implement these methods so that they take hashCode() and
equals(...) of the wrapped value into an account.

Basically, hashCode() and equals(...) should operate with name, declaredType,
scope, nil AND value fields.

I can implement these methods, but I need to know, where to find the jaxb-api
project sources...

Bye.
/lexi

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 EA1]

Remove checked Exception from ObjectFactory factory methods

There is a request for JAXB 2.0 to no longer require that
the factory method signatures in ObjectFactory throw the
checked exception JAXBException.

Rationale:
In Java, creating new instances of objects do not fail with a
checked exception. This is because:

• it's not hard to imagine how many try-catch blocks you'll
  be writing if every "new" throws an exception.
• unlike errors like I/O problems, which you can handle gracefully,
  there's really nothing you can do to recover from failing to
  create new instances in memory.

Specific request is to change following text in Section 5.2 of JAXB 2.0 Early
Draft

A public class ObjectFactory contains:
An instance factory method signature for each Java content within the package.

Given Java content interface named Foo, here is the derived factory method:

public Foo createFoo() throws JAXBException;
An element instance factory method signature for each bound element declaration.

public IXmlElement createFoo(T elementValue)
throws JAXBException;
Dynamic instance factory allocator method signature:

public Object newInstance(Class javaContentInterface)
throws JAXBException;

Change is to delete "throws JAXBException" from above factory method
signatures of ObjectFactory.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

XMLGregorianCalendar's handling of daylight savings timezone

Submitted by Dennis Sosnoski, entered by Joe Fialli.

There is an incompatibility between the Java and XML Schema concept
of timezone that impacts javax.xml.datatype.XMLGregorianCalendar.

The Java concept of timezone provides for daylight savings time to enter
into Calendar operations.

Extracted from java.util.TimeZone javadoc.

• TimeZone represents a time zone offset, and also figures out daylight savings.
• No daylight saving time transition schedule can be specified with a custom
  time zone ID.

The XML Schema representation of timezone is only in UTC and there is no
means to represent a daylight savings timezone in XML format nor to compensate
for daylight savings transitions in calendar computations.
Dennis suggests that to keep this clear to the users the setTimeZone method
of XMLGregorianCalendar should be specified to allow only constant time
zones and should throw a runtime exception if the user tries to set a
time zone that incorporates daylight saving time transitions.

Another suggestion in the expert group is that the data representation should
not incorporate the XML Schema restriction, only the act of marshalling
an instance of XMLGregorianCalendar to XML native format should normalize
the value to lose its daylight savings transition schedule.

Here is an example of how daylight savings transition schedule impacts
an operation.

If one adds 6 months to a dateTime with a time of 6:00 and the Java representation
for timezone has a daylight savings transition schedule, the time will be
either one hour less or more of the original 6:00. However, if the Java
representation
did not have a daylight savings timezone, no change would occur.

All instances of XMLGregorianCalendar that are unmarshalled from XML content
could never have a daylight savings timezone, since there is no way to represent
this info in XML Schema. However, instances of XMLGregorianCalendar created
within a Java application by a user, could easily have a daylight savings timezone,
especially if the default timezone is a daylight savings timezone. Supporting
Dennis' proposal, JAXB has a requirement to be able to marshal from Java to
XMl and back to Java and have the two Java representations be identical.
If the original Java calendar had a daylight savings timezone, there is no
way to preserve this in the roundtrip from Java to XML to Java again.
It can be potentially confusing to have the behavior of adding 6 months
work differently based on whether the XMLGregorianCalendar was created in
the Java application vs unmarshalled from XML content.

---

The following needs to be reflected in the comparison operations on
XMLGregorianCalendar.

The comparison of dateTime values is specified that two dateTimes are equal if

• they both have time zones and the normalized (UTC) values are the same
• are both in unknown time zones with the same values.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

Bug in @XmlElement.name javadoc

public @interface XmlElement {
/**

• Name of the XML Schema element. By default, the XML Schema
• element name is derived from the JavaBean property name.

*/
String name() default "";

This customization might be used on a class, so just saying
"from the JavaBean property name" is inaccurate. You should say
something like:

... from (1) the JavaBean property name if the customization is
spcified on a method or a field and (2) the class name if the
customization is specified on a class.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 v0.4]

@XmlValue too restrictive

The clause "@XmlValue must be the only mapping annotation on the JavaBean
property" in javadoc is too strong. You should be able to use other annotations,
such as XmlID, XmlIDREF, or XmlJavaTypeAdapter.

This phrase should be modified to "@XmlValue, @XmlAttribute, and @xmlelement are
mutually exclusive and may not be on one property at the same time"

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

mapping to substitution groups

Should a mapping of existing classes to substitution groups be
specified ?

It was resolved in the EG conf call on March 16, 2004 that there would
be no mapping of existing classes to substitution groups. From the
bullet item 3.2 in the mintues:

https://www.dev.java.net/files/documents/919/3410/Mar-16-2004.txt

3.2 Mapping of substitution groups
Should a mapping to substitution groups specified ?
Opinion poll of experts indicated not much support for this
feature.

RESOLUTION: Mapping to substitution groups is not supported.

Note 3.2 header should read "Mapping to substitution groups" instead
of "Mapping of substitution groups".

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

parse method takes CharSequence, not String

Submitted by David Bau, entered initially by Joe Fialli

For javax.xml.datatype.Duration and javax.xml.datatype.XMLGregorianCalendar,
the parser methods have a parameter of type String. To enable efficient
implementations that take advantage of java.nio, it would be preferable
if these parse methods took a CharSequence instead. In JDK 1.4, String
implements CharSequence.

Note that javax.xml.bind.DatatypeConverterInterface and DatatypeConverter
would also need to be changed to make the most of efficiencies being requested
by this change.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

default Java binding for xsd:anyURI

Recommendation to default xsd:anyURI to string.

Pro:

• Alignment with JAX-RPC 2.0: JAX-RCP 1.1 defaults xsd:anyURI to java.net.URI.
  (Need to have JAX-RPC expert group evaluate JAXB feedback.)

Con:

• Since the URI spec (RFC 2396 & 2732) is notoriously ambiguous,
  and end-users use lots of different strings
  for URIs that are potentially not strictly permitted by the URI RFC
  spec.
  java.net.URI is already a loose interpretation of the spec, but not
  loose
  enough for all URIs that appear in XML documents.
  Clarification request: are there URIs that XML Schema validation would
  state are legal that java.net.URI would not be able to represent?
• java.net.URI is a larger physical representation than string.
• JAXB 1.0 defaulted to string.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

mapping : Generation of schema from sources

This issue was originally raised by David Bau.

This issue was originally raised by David Bau.
---- [ Start: David Bau's comment ] -----
The XML schema can Doesn't java.beans.Introspector assume that the
class is already compiled and loadable? What about producing schema
from Java sources? Depending on Introspector to specify a code
generation rule seems to me a violation of a separation between
compiletime (binding) and runtime.

---- [ End: David Bau's comment ] -----

The following are the implications for the JAXB 2.0 specification:

1. use of java.beans.Introspector to determine the properties will
require a retention policy of RetentionPolicy.RUNTIME on the JAXB
annotations.

TBD. Add any additional notes from expert group discussion.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

@XmlCollection.values should be "value"

Otherwise people will be forced to write:

@XmlCollection(values=

{ @XmlCollectionItem(type=Ref4.class) })
List w;

Instead of :

@XmlCollection({ @XmlCollectionItem(type=Ref4.class) }

)
List w;

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

Spec format - abstaract schema components or surface syntax

This issue (and the following text) was described in Chapter 8, "Java
to XML", Section 8.15.2, "Issue: Spec format - abstract schema
components verus surface syntax". I moved the text out of the chapter
into this issue to clean up chapter 8 for Early Draft version of the
specification.

– Start: Text of the issue from Chapter 8 –

Note - Resolution : Specify in terms of abstract schema components.
Note - This issue is related to the format in which the specification
is written and otherwise does not contribute to the actual
content of the specification.

There can be more than one surface syntactic representation for a
schema component. So the issue is:

Should the mapping of Java to XML schema he Java->Generated XML
schema be specified in terms of surface syntax or abstract schema
components defined by the XML Schema specification ?

For example, the following XML schema fragment from XSD Part 0,
Primer(the namespace prefix has been changed from xsd: to xs:, used in
XML Schema->Java in JAXB 1.0 specification).

<xs:complexType name="PurchaseOrderType">
xs:sequence
<xs:element name="shipTo" type="USAddress"/>
<xs:element name="billTo" type="USAddress"/>
<xs:element ref="comment" minOccurs="0"/>
<xs:element name="items" type="Items"/>
</xs:sequence>
<xs:attribute name="orderDate" type="xsd:date"/>
</xs:complexType>

The above XML schema fragment can equivalently be written as:

<xs:complexType name="PurchaseOrderType">
xs:complexContent
<xs:restriction base="xs:anyType">
xs:sequence
<xs:element name="shipTo" type="USAddress"/>
<xs:element name="billTo" type="USAddress"/>
<xs:element ref="comment" minOccurs="0"/>
<xs:element name="items" type="Items"/>
</xs:sequence>
</xs:restriction>
</xs:complexContent>
<xs:attribute name="orderDate" type="xsd:date"/>
</xs:complexType>

For this version of the document, the mapping in terms of abstract of
schema components is assumed.One or more examples will also be shown
in one surface syntax. However, the examples will be non-normative.

– End: Text of the issue from chapter 8 –

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

mapping class -> complex type with xs:all compositor

This issue has already been resolved. So the following text is from
the issue that is being moved out of the specification in preparation
for the Early Draft of the specification.

XML schema imposes several restrictions on the use of xs:all, which in
turn limit the mapping of Java class to xs:all. However, xs:all can be
used to represent unordered content. It was agreed in the expert group
conference call on March 16, 2004 that limited mapping a Java class to
xs:all would be useful.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

xjc can't handle the restriction complext type

Hi,

We are Celtix team[1], and we are using JAXB 2.0 EA3.
But with the attached testcase, we have the following errors throwed from
JAXB RI.

[java] Parsing schema error:
[java] org.xml.sax.SAXParseException: Base complex type "RestrictedCard" is
derived by restriction, while this complex type "
ard" is derived by extension. This is not currently handled by XJC, but we are
seeking input on this issue. Please report this to
the JAXB team.
[java] Error : An rpc-literal binding in a DESCRIPTION MUST refer, in its
soapbind:body element(s), only to wsdl:part element
s) that have been defined using the type attribute.

[java] An rpc-literal binding in a DESCRIPTION MUST refer, in its
soapbind:body element(s), only to wsdl:part element(s) that
have been defined using the type attribute.

Any help will be appreciate.

[1] http://celtix.objectweb.org/

Thanks,
James.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 EA1]

Improving error handling of JAXBContext.newInstance

Today, the bootstrap mechanism roughly works like the following:

1. an application invokes JAXBContext.newInstance()
2. the JAXB API determines the provider
3. the JAXB API calls into the provider code to create a new factory
4. the provider code returns with an initialized JAXBContext
5. the JAXB API returns it to the app

If the exception is thrown between step 3 and 4 from the provider code,
right now the user receives a JAXBException that wraps
InvocationTargetException that wraps the thrown exception.

This wrapping is bit too deep and makes it harder to track down the problem.

A better way would be to change the API code so that when it receives
an InvocationTargetException, it wraps the target exception directly into
the JAXBException.

By the same token, if the provider code throws an Error, it shouldn't be
wrapped to JAXBException, because an Error usually indicates more
serious problem (such as OutOfMemoryError) and throwing an Error directly
makes it easier for users to find out the cause of the problem.

Similarly, a RuntimeException indicates a bug in the provider code, and
that should be thrown directly so that it is clear to the user that it is
a provider's problem, not JAXB API's problem.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 v0.4]

XMLGregorianCalendar must have stable field getters

Submitted by David Bau, entered by Joe Fialli.

It is not documented, but it is important that, unlike the other Calendar
implementations in the JDK, the field getters are stable, i.e., if you say
"get(FIELD)", it does not force other unset fields to be completed. For
example, if you say "get(MONTH)" today, then even if you do not have a
"SECONDS" or "YEAR" field, those filled in for you. That is really bad when
your data is a gMonth.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

XMLGregorianCalendar parsing enhancements

Submitted by David Bau, entered initially by Joe Fialli

Rather than having eight separate parsing functions, (for all of the g*, date,
dateTime
datatypes), there simply should be one parsing function that can accept all the
forms
(with any of the five subfields Y/M/D/time/timezone omitted); this is simple
to implement; it would be a simpler API; it is a nice solution for unions;
and validators could use a getXmlSchemaType() method to verify that the
proper form were loaded.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

mapping class-> complex type with element only content

The mapping of a Java class properties/fields to a complex type
definition with element only content was suggested in the conference
calls as being useful.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 draft]

mapping: @XmlType.name() inconsistent in javadoc and spec

The javadoc and specification in Chapter 8 are inconsistent in the
treatment of the @XmlType.name() annotation parameter. The references
to chapter 8 below are from JAXB 2.0 v0.42.

a. The javadoc indicates @XmlType.name() is required.
but the default mapping in section 8.8.1.3 omits it.

b. The mapping tables 8-4 (which maps a class to a complex type) and
8-6 (which maps a class to a simple type) allow @XmlType.name() to be "".
But the javadoc does not define the semantics when @XmlType.name() is "".

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 v0.4]

allow @XmlElementWrapper on any property

Currently, @XmlElementWrapper is only allowed on Collection properties. It
would be useful to allow this annotation on any property to supported nested XML
that doesn't necessarily make sense in the object model. For example:

@XmlElementWrapper(name="sessionTimeout")
@xmlelement(name="seconds")
private Seconds sessionTimeout;

To produce:

60

Environment

Operating System: All
Platform: All

Affected Versions

[2.1 EA1]

XmlJTypeAdapter javadoc is sketchy

The printMethod and the parseMethod should say exactly what is allowed.

As I understand it

• "new" to invoke the constructor
• just a method name (e.g., "toString") to invoke an instance method
• a fully qualified method name (e.g., "abc.def.Ghi.jkl") to invoke a static
  method.

Environment

Operating System: All
Platform: All

Affected Versions

[2.0 v0.4]