libraries/conversion/src/docs/conversion.txt

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

[[library-conversion, Conversion Library]]
= Conversion - DEPRECATED =

[devstatus]
--------------
source=libraries/conversion/dev-status.xml
--------------

The Conversion Library provides support for converting composite types.

include::../../build/docs/buildinfo/artifact.txt[]


[WARNING]
.DEPRECATED
====
This functionality is now present in <<def-unitofwork>> as
the two methods toEntity() and toValue(). Since this library was written
assocations of all kinds are now fully supported in Values.
====


== Entities to Values ==

To convert Entities to Values, use the EntityToValueService. It is easily assembled:

[snippet,java]
----
source=libraries/conversion/src/test/java/org/qi4j/library/conversion/values/EntityToValueTest.java
tag=assembly
----

Let's say we have an interface defining state:

[snippet,java]
----
source=libraries/conversion/src/test/java/org/qi4j/library/conversion/values/TestModel.java
tag=state
----

An EntityComposite using the state as a Private Mixin:

[snippet,java]
----
source=libraries/conversion/src/test/java/org/qi4j/library/conversion/values/TestModel.java
tag=entity
----

And a ValueComposite extending this very same state;

[snippet,java]
----
source=libraries/conversion/src/test/java/org/qi4j/library/conversion/values/TestModel.java
tag=value
----

Here is how to convert an EntityComposite to a ValueComposite:

[snippet,java]
----
source=libraries/conversion/src/test/java/org/qi4j/library/conversion/values/EntityToValueTest.java
tag=conversion
----


== Values to Entities ==

Using the ValueToEntity service one can create new Entities or update existing ones from Values.
It is easy assembled:

[snippet,java]
----
source=libraries/conversion/src/test/java/org/qi4j/library/conversion/values/ValueToEntityTest.java
tag=assembly
----

Let's say we have the exact same model as described above.

Here is how to create an EntityComposite from a ValueComposite:

[snippet,java]
----
source=libraries/conversion/src/test/java/org/qi4j/library/conversion/values/ValueToEntityTest.java
tag=creation
----

Here is how to update an EntityComposite from a ValueComposite:

[snippet,java]
----
source=libraries/conversion/src/test/java/org/qi4j/library/conversion/values/ValueToEntityTest.java
tag=update
----


== Associations are converted to Identity strings ==

If your Entities and Values cannot use the same state type, you can annotate the Value that is the target of the
conversion with the `@Unqualified` annotation. Then, the lookup of the Value Property will be performed using the
*unqualified* name only, and not via the default of the full qualified name. In other words, this means that the
Property may be declared in the different interfaces and still be matched.

Here is an example:

[snippet,java]
----
source=libraries/conversion/src/test/java/org/qi4j/library/conversion/values/TestModel.java
tag=unqualified
----