= JaxbService
:Notice: Licensed to the Apache Software Foundation (ASF) under one or more contributor license agreements. See the NOTICE file distributed with this work for additional information regarding copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at. http://www.apache.org/licenses/LICENSE-2.0 . Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR  CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

Allows instances of JAXB-annotated classes to be marshalled to XML and unmarshalled from XML back into domain objects.

The default implementation automatically caches the JAXB marshallers by target class.

== API

[source,java]
.JaxbService.java
----
interface JaxbService {
  T fromXml(Class<T> domainClass, String xml)     // <.>
  T fromXml(Class<T> domainClass, String xml, Map<String, Object> unmarshallerProperties)     // <.>
  String toXml(Object domainObject)     // <.>
  String toXml(Object domainObject, Map<String, Object> marshallerProperties)     // <.>
  Map<String, String> toXsd(Object domainObject, CausewaySchemas causewaySchemas)     // <.>
}
----

<.> xref:#fromXml_Class_String[fromXml(Class, String)]
+
--
Unmarshalls the XML to the specified domain class.
--
<.> xref:#fromXml_Class_String_Map[fromXml(Class, String, Map)]
+
--
Unmarshalls the XML to the specified domain class, with additional properties passed through to the _JAXBContext_ used to performed the unmarshalling.
--
<.> xref:#toXml_Object[toXml(Object)]
+
--
Marshalls the object into XML (using a _JAXBContext_ for the object's class).
--
<.> xref:#toXml_Object_Map[toXml(Object, Map)]
+
--
Marshalls the object into XML specifying additional properties (passed to the _JAXBContext_ used for the object's class).
--
<.> xref:#toXsd_Object_CausewaySchemas[toXsd(Object, CausewaySchemas)]
+
--
Generates a map of each of the schemas referenced; the key is the schema namespace, the value is the XML of the schema itself.
--

== Members

[#fromXml_Class_String]
=== fromXml(Class, String)

Unmarshalls the XML to the specified domain class.

[#fromXml_Class_String_Map]
=== fromXml(Class, String, Map)

Unmarshalls the XML to the specified domain class, with additional properties passed through to the _JAXBContext_ used to performed the unmarshalling.

[#toXml_Object]
=== toXml(Object)

Marshalls the object into XML (using a _JAXBContext_ for the object's class).

[#toXml_Object_Map]
=== toXml(Object, Map)

Marshalls the object into XML specifying additional properties (passed to the _JAXBContext_ used for the object's class).

[#toXsd_Object_CausewaySchemas]
=== toXsd(Object, CausewaySchemas)

Generates a map of each of the schemas referenced; the key is the schema namespace, the value is the XML of the schema itself.

A JAXB-annotated domain object will live in its own XSD namespace and may reference multiple other XSD schemas. In particular, many JAXB domain objects will reference the common causeway schemas. The xref:refguide:applib:index/services/jaxb/CausewaySchemas.adoc[CausewaySchemas] paramter indicates whether these schemas should be included or excluded from the map.

include::hooks/JaxbService_010-implementation.adoc[]

include::hooks/JaxbService_020-examples-and-usage.adoc[]
