Jump to: navigation, search

Difference between revisions of "EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Basic Mappings/Lob"

m
(Lazy)
 
(12 intermediate revisions by 2 users not shown)
Line 1: Line 1:
{{EclipseLink_UserGuide|info=y|toc=n}}
+
{{EclipseLink_UserGuide
 +
|info=y
 +
|toc=n
 +
|eclipselink=y
 +
|eclipselinktype=JPA
 +
|api=y
 +
|apis=
 +
* [http://www.eclipse.org/eclipselink/api/latest/javax/persistence/Lob.html @Lob]
 +
}}
 +
 
 
=@Lob=
 
=@Lob=
By default, EclipseLink persistence provider assumes that all persistent data can be represented as typical database data types.
+
By default, the EclipseLink persistence provider assumes that all persistent data can be represented as typical database data types.
  
Use the <tt>@Lob</tt> annotation with the [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings|<tt>@Basic</tt> mapping]] to specify that a persistent property or field should be persisted as a large object to a database-supported large object type.
+
Use the <tt>@Lob</tt> annotation with the [[EclipseLink/UserGuide/JPA/Basic_JPA_Development/Mapping/Basic_Mappings|<tt>@Basic</tt>]] mapping to specify that a persistent property or field should be persisted as a large object to a database-supported large object type.
  
 
A <tt>Lob</tt> may be either a binary or character type. The persistence provider infers the <tt>Lob</tt> type from the type of the persistent field or property.
 
A <tt>Lob</tt> may be either a binary or character type. The persistence provider infers the <tt>Lob</tt> type from the type of the persistent field or property.
Line 11: Line 20:
 
You can also use the <tt>@Column</tt> attribute <tt>columnDefinition</tt> to further refine the <tt>Lob</tt> type.
 
You can also use the <tt>@Column</tt> attribute <tt>columnDefinition</tt> to further refine the <tt>Lob</tt> type.
 
{{EclipseLink_Spec
 
{{EclipseLink_Spec
|section=Section 9.1.5 "Column Annotation"}}
+
|section=Section 11.1.9 "Column Annotation"}}
  
 
The <tt>@Lob</tt> annotation does not have attributes.
 
The <tt>@Lob</tt> annotation does not have attributes.
Line 19: Line 28:
 
======'' Example: @Lob''======
 
======'' Example: @Lob''======
 
<source lang="java">
 
<source lang="java">
@Entity
+
@Entity
public class Employee implements Serializable {
+
public class Employee implements Serializable {
    ...
+
    ...
    @Lob
+
    @Lob
    @Basic(fetch=LAZY)
+
    @Basic(fetch=LAZY)
    @Column(name="EMP_PIC", columnDefinition="BLOB NOT NULL")
+
    @Column(name="EMP_PIC", columnDefinition="BLOB NOT NULL")
    protected byte[] pic;
+
    protected byte[] pic;
    ...
+
    ...
}
+
}
 +
</source>
 +
 
 +
======''Example: Using <code><nowiki><lob></nowiki></code> XML''======
 +
<source lang="xml">
 +
<entity class="Employee">
 +
    <attributes>
 +
        ...
 +
        <basic name="pic">
 +
            <column name="EMP_PIC" column-definition="BLOB NOT NULL"/>
 +
            <lob/>
 +
        </basic>
 +
        ...
 +
    </attributes>
 +
</entity>
 
</source>
 
</source>
  
 
{{EclipseLink_Spec
 
{{EclipseLink_Spec
|section=Section 9.1.20 "Temporal Annotation"}}
+
|section=Section 11.1.24 "Lob Annotation"}}
  
 +
====Serialization====
 +
Although a BLOB is stored as a <code>byte[]</code>, the Java a type for a <code>@Lob</code> mapping can be any serializable type.  JPA will automatically serialize and store the value into a BLOB field, and deserialize the value when read.
  
 +
====Lazy====
 +
If the LOB field is large, and may not always be required, it is normally a good idea to set its <code>fetch</code> type to <code>LAZY</code> using the <code>@Basic</code> annotation.
 +
 +
Sometimes it is better to move the LOB to its own table and create an entity class to wrap it.  This avoids any overhead or limitations of the LOB in the owning entity class, which can define a LAZY OneToOne relationship to the LOB.
 +
 +
====Database Limitations====
 +
Some databases have size limitations for LOB fields, or requires large LOBs be written to the database in specific ways.
 +
 +
EclipseLink supports using a LOB locator to write LOBs on Oracle.  This was required to write LOBs > 4k when using the Oracle JDBC thin driver until Oracle 11g.  If the <code>Oracle8Platform</code> or higher (until <code>Oracle11Platform</code>) is used LOBs will be written using a locator.  This can be configured in the database platform.
 +
 +
EclipseLink by default binds LOB values as <code>byte[]</code> or <code>String</code>.  Some databases or JDBC drivers may require stream binding.  Stream binding can be configured in the database platform in code, using a <code>SessionCustomizer</code>
 +
 +
======''Using a SessionCustomizer to enable stream binding''======
 +
<source lang="java">
 +
@Entity
 +
public class MyCustomizer implements SessionCustomizer {
 +
    public void customize(Session session) {
 +
        session.getLogin().setUsesStreamsForBinding(true);
 +
    }
 +
}
 +
</source>
 +
 +
====Very Large LOBs====
 +
If your LOB is very large, such that it is not desirable to bring into memory, then it should not be mapped.  It could be queried directly, using JDBC and streamed to avoid every being read into memory.  The JDBC <code>Connection</code> can be obtained in JPA using the <code>unwrap()</code> API on <code>EntityManager</code>.
 +
 +
<source lang="java">
 +
java.sql.Connection connection = em.unwrap(java.sql.Connection.class);
 +
</source>
  
 
{{EclipseLink_JPA
 
{{EclipseLink_JPA

Latest revision as of 14:27, 23 May 2012

EclipseLink JPA

link="http://wiki.eclipse.org/EclipseLink"
EclipseLink
Website
Download
Community
Mailing ListForumsIRC
Bugzilla
Open
Help Wanted
Bug Day
Contribute
Browse Source

Elug api package icon.png Key API


@Lob

By default, the EclipseLink persistence provider assumes that all persistent data can be represented as typical database data types.

Use the @Lob annotation with the @Basic mapping to specify that a persistent property or field should be persisted as a large object to a database-supported large object type.

A Lob may be either a binary or character type. The persistence provider infers the Lob type from the type of the persistent field or property.

For String and character-based types, the default is Clob. In all other cases, the default is Blob.

You can also use the @Column attribute columnDefinition to further refine the Lob type.

Elug javaspec icon.gif

For more information, see Section 11.1.9 "Column Annotation" in the JPA Specification.

The @Lob annotation does not have attributes.

The following example shows how to use this @Lob annotation to specify that persistent field pic should be persisted as a Blob.

Example: @Lob
@Entity
public class Employee implements Serializable {
    ...
    @Lob
    @Basic(fetch=LAZY)
    @Column(name="EMP_PIC", columnDefinition="BLOB NOT NULL")
    protected byte[] pic;
    ...
}
Example: Using <lob> XML
<entity class="Employee">
    <attributes>
        ...
        <basic name="pic">
            <column name="EMP_PIC" column-definition="BLOB NOT NULL"/>
            <lob/>
        </basic>
        ...
    </attributes>
</entity>
Elug javaspec icon.gif

For more information, see Section 11.1.24 "Lob Annotation" in the JPA Specification.

Serialization

Although a BLOB is stored as a byte[], the Java a type for a @Lob mapping can be any serializable type. JPA will automatically serialize and store the value into a BLOB field, and deserialize the value when read.

Lazy

If the LOB field is large, and may not always be required, it is normally a good idea to set its fetch type to LAZY using the @Basic annotation.

Sometimes it is better to move the LOB to its own table and create an entity class to wrap it. This avoids any overhead or limitations of the LOB in the owning entity class, which can define a LAZY OneToOne relationship to the LOB.

Database Limitations

Some databases have size limitations for LOB fields, or requires large LOBs be written to the database in specific ways.

EclipseLink supports using a LOB locator to write LOBs on Oracle. This was required to write LOBs > 4k when using the Oracle JDBC thin driver until Oracle 11g. If the Oracle8Platform or higher (until Oracle11Platform) is used LOBs will be written using a locator. This can be configured in the database platform.

EclipseLink by default binds LOB values as byte[] or String. Some databases or JDBC drivers may require stream binding. Stream binding can be configured in the database platform in code, using a SessionCustomizer

Using a SessionCustomizer to enable stream binding
@Entity
public class MyCustomizer implements SessionCustomizer {
    public void customize(Session session) {
        session.getLogin().setUsesStreamsForBinding(true);
    }
}

Very Large LOBs

If your LOB is very large, such that it is not desirable to bring into memory, then it should not be mapped. It could be queried directly, using JDBC and streamed to avoid every being read into memory. The JDBC Connection can be obtained in JPA using the unwrap() API on EntityManager.

java.sql.Connection connection = em.unwrap(java.sql.Connection.class);

Eclipselink-logo.gif
Version: 2.1.0
Other versions...