EclipseLink/UserGuide/JPA/Basic JPA Development/Mapping/Basic Mappings/Lob

EclipseLink JPA

• EclipseLink Destinations:
• Documentation
• FAQ
• Examples
• Development

Key API

• @Lob

@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.

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>

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);

Version: 2.1.0
Other versions...

@Temporal	Basic Mappings	@Transient
EclipseLink Home JPA User Guide: Table of Contents, Search
How to contribute to this guide...