| /******************************************************************************* |
| * Copyright (c) 2013 Oracle and/or its affiliates. All rights reserved. |
| * This program and the accompanying materials are made available under the |
| * terms of the Eclipse Public License v1.0 and Eclipse Distribution License v. 1.0 |
| * which accompanies this distribution. |
| * The Eclipse Public License is available at http://www.eclipse.org/legal/epl-v10.html |
| * and the Eclipse Distribution License is available at |
| * http://www.eclipse.org/org/documents/edl-v10.php. |
| * |
| * Contributors: |
| * 24 April 2013-2.5.1 ailitche |
| * SerializedObjectPolicy initial API and implementation |
| ******************************************************************************/ |
| package org.eclipse.persistence.annotations; |
| |
| import static java.lang.annotation.ElementType.TYPE; |
| import static java.lang.annotation.RetentionPolicy.RUNTIME; |
| |
| import java.lang.annotation.Retention; |
| import java.lang.annotation.Target; |
| |
| import javax.persistence.Column; |
| |
| /** |
| * SerializedObject annotation is used to set an |
| * org.eclipse.persistence.descriptors.SerializedObjectPolicy on an Entity or MappedSuperClass. |
| * |
| * If SerializedObjectPolicy is specified Eclipselink writes out the whole entity object with its |
| * privately owned (and nested privately owned) entities and element collections into an additional |
| * (likely BLOB) field in the database. That field could be specified in the annotation, it defaults to "SOP" in the main table. |
| * |
| * <p> |
| * Examples: |
| * <code><pre> |
| * @Entity |
| * @SerializedObject(MySerializedObjectPolicy.class); |
| * public class Employee {... |
| * </pre></code> |
| * <code><pre> |
| * @Entity |
| * @SerializedObject(value = MySerializedObjectPolicy.class, column = @Column(name="SERIALIZED")); |
| * public class Address {... |
| * </pre></code> |
| * |
| * If SerializedObjectPolicy is set on an entity then SerializedObjectPolicies with the same field are set |
| * on all inheriting entities. |
| * |
| * The query that uses SerializedObjectPolicy extracts the whole object from that field. |
| * To read object(s) using SerializedObjectPolicy the query should specify |
| * @see QueryHints#SERIALIZED_OBJECT |
| * |
| * <p> |
| * Examples: |
| * <code><pre> |
| * Query query = em.createQuery("SELECT e FROM Employee e").setHint(QueryHints.SERIALIZED_OBJECT, "true"); |
| * </pre></code> |
| * <code><pre> |
| * Map hints = new HashMap(); |
| * hints.put("eclipselink.serialized-object", "true"); |
| * Address address = em.find(Address.class, id, hints); |
| * </pre></code> |
| * |
| * The goal is to make reads from the database faster. |
| * The draw back is slower writes into the database. |
| * So SerializedObjectPolicy may make sense for read-only / read-mostly application |
| * for Entity, which always loads all its dependent entities and / or ElementCollections. |
| * |
| * In case the serialized object column contains null or obsolete version of the object |
| * the query using SerializedObjectPolicy would either throw exception or - if all other fields have been read, too - |
| * would build the object using these fields (exactly as in case SerializedObjectPolicy is not used). |
| * |
| * Note that currently no default implementation of SerializedObjectPolicy is available |
| * and this class should be provided by the user. |
| * |
| * @see org.eclipse.persistence.descriptors.SerializedObject |
| * |
| * @author ailitche |
| * @since EclipseLink 2.5.1 |
| * |
| * @see SerializedObjectPolicy |
| */ |
| @Target({TYPE}) |
| @Retention(RUNTIME) |
| public @interface SerializedObject { |
| /** |
| * The Class that implements org.eclipse.persistence.descriptors.SerializedObjectPolicy interface. |
| * This class must be specified. |
| */ |
| Class value(); |
| |
| /** |
| * (Optional) The column that holds the serialized object. By default it's a BLOB column named "SOP" in entity's main table. |
| */ |
| Column column() default @Column(name="SOP"); |
| } |