diff --git a/documentation/src/main/docbook/devguide/en-US/Data_Operations.xml b/documentation/src/main/docbook/devguide/en-US/Data_Operations.xml
new file mode 100644
index 0000000000..f3bac21223
--- /dev/null
+++ b/documentation/src/main/docbook/devguide/en-US/Data_Operations.xml
@@ -0,0 +1,310 @@
+
+
+%BOOK_ENTITIES;
+]>
+
+ Working with entities
+
+
+ Both the org.hibernate.Session API and
+ javax.persistence.EntityManager API provide methods for working with entities.
+ This chapter will explore the available operations in each.
+
+
+
+ Entity states
+
+
+ new, or transient - the entity has just been instantiated and is
+ not associated with a persistence context. It has no persistent representation in the database and no
+ identifier value has been assigned.
+
+
+
+
+ managed, or persistent - the entity has an associated identifier
+ and is associated with a persistence context.
+
+
+
+
+ detached - the entity has an associated identifier, but is no longer associated with
+ a persistence context (usually because the persistence context was closed or the instance was evicted
+ from the context)
+
+
+
+
+ removed - the entity has an associated identifier and is associated with a persistence
+ context, however it is scheduled for removal from the database.
+
+
+
+
+
+
+
+ In Hibernate native APIs, the persistence context is defined as the
+ org.hibernate.Session. In JPA, the persistence context is defined by
+ javax.persistence.EntityManager. Much of the
+ org.hibernate.Session and
+ javax.persistence.EntityManager methods deal with moving entities between these
+ states.
+
+
+
+ Making entities persistent
+
+
+ Once you've created a new entity instance (using the standard new operator) it is in
+ new state. You can make it persistent by associating it to either a
+ org.hibernate.Session or
+ javax.persistence.EntityManager
+
+
+
+ Example of making an entity persistent
+
+
+
+
+
+
+
+
+
+
+ org.hibernate.Session also has a method named persist
+ which follows the exact semantic defined in the JPA specification for the persist
+ method. It is this method on org.hibernate.Session to which the
+ Hibernate javax.persistence.EntityManager implementation delegates.
+
+
+
+
+ If the DomesticCat entity type has a generated identifier, the value is associated
+ to the instance when the save or persist is called. If the
+ identifier is not automatically generated, the application-assigned (usually natural) key value has to be
+ set on the instance before save or persist is called.
+
+
+
+
+ Deleting entities
+
+ Entities can also be deleted.
+
+
+ Example of deleting an entity
+
+
+
+
+
+
+
+
+ It is important to note that Hibernate itself can handle deleting detached state. JPA, however, disallows
+ it. The implication here is that the entity instance passed to the
+ org.hibernate.Session delete method can be either
+ in managed or detached state, while the entity instance passed to remove on
+ javax.persistence.EntityManager must be in managed state.
+
+
+
+
+ Obtain an entity reference without initializing its data
+
+ Sometimes referred to as lazy loading, the ability to obtain a reference to an entity without having to
+ load its data is hugely important. The most common case being the need to create an association between
+ an entity and another, existing entity.
+
+
+ Example of obtaining an entity reference without initializing its data
+
+
+
+
+
+
+
+
+ The above works on the assumption that the entity is defined to allow lazy loading, generally through
+ use of runtime proxies. For more information see . In both
+ cases an exception will be thrown later if the given entity does not refer to actual database state if and
+ when the application attempts to use the returned proxy.
+
+
+
+
+ Obtain an entity with its data initialized
+
+
+ It is also quite common to want to obtain an entity along with with its data, for display for example.
+
+
+ Example of obtaining an entity reference with its data initialized
+
+
+
+
+
+
+
+
+ In both cases null is returned if no matching database row was found.
+
+
+
+
+ Refresh entity state
+
+
+ You can reload an entity instance and it's collections at any time.
+
+
+
+ Example of refreshing entity state
+
+
+
+
+
+
+
+
+
+ One case where this is useful is when it is known that the database state has changed since the data was
+ read. Refreshing allows the current database state to be pulled into the entity instance and the
+ persistence context.
+
+
+
+ Another case where this might be useful is when database triggers are used to initialize some of the
+ properties of the entity. Note that only the entity instance and its collections are refreshed unless you
+ specify REFRESH as a cascade style of any associations. However, please note that
+ Hibernate has the capability to handle this automatically through its notion of generated properties.
+ See for information.
+
+
+
+
+ Modifying managed/persistent state
+
+
+ Entities in managed/persistent state may be manipulated by the application and any changes will be
+ automatically detected and persisted when the persistence context is flushed. There is no need to call a
+ particular method to make your modifications persistent.
+
+
+
+ Example of modifying managed state
+
+
+
+
+
+
+
+
+
+
+ Working with detached data
+
+
+ Detachment is the process of working with data outside the scope of any persistence context. Data becomes
+ detached in a number of ways. Once the persistence context is closed, all data that was associated with it
+ becomes detached. Clearing the persistence context has the same effect. Evicting a particular entity
+ from the persistence context makes it detached. And finally, serialization will make the deserialized form
+ be detached (the original instance is still managed).
+
+
+
+ Detached data can still be manipulated, however the persistence context will no longer automatically know
+ about these modification and the application will need to intervene to make the changes persistent.
+
+
+
+ Reattaching detached data
+
+ Reattachment is the process of taking an incoming entity instance that is in detached state
+ and re-associating it with the current persistence context.
+
+
+
+ JPA does not provide for this model. This is only available through Hibernate
+ org.hibernate.Session.
+
+
+
+ Example of reattaching a detached entity
+
+
+
+
+
+
+
+
+ The method name update is a bit misleading here. It does not mean that an
+ SQL UPDATE is immediately performed. It does, however, mean that an
+ SQL UPDATE will be performed when the persistence context is flushed
+ since Hibernate does not know its previous state against which to compare for changes.
+
+
+ Provided the entity is detached, update and saveOrUpdate
+ operate exactly the same.
+
+
+
+
+ Merging detached data
+
+ Merging is the process of taking an incoming entity instance that is in detached state and copying its
+ data over onto a new instance that is in managed state.
+
+
+ Visualizing merge
+
+
+
+
+
+ That is not exactly what happens, but its a good visualization.
+
+
+ Example of merging a detached entity
+
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/documentation/src/main/docbook/devguide/en-US/Hibernate_Development_Guide.xml b/documentation/src/main/docbook/devguide/en-US/Hibernate_Development_Guide.xml
index 6f66ecb69f..1fed9ef209 100644
--- a/documentation/src/main/docbook/devguide/en-US/Hibernate_Development_Guide.xml
+++ b/documentation/src/main/docbook/devguide/en-US/Hibernate_Development_Guide.xml
@@ -8,6 +8,7 @@
+