Jump to: navigation, search

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

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;
    ...
}
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.

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