org.eclipse.persistence.dynamic.DynamicEntity Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of eclipselink Show documentation
EclipseLink build based upon Git transaction f2b9fc5
There is a newer version: 5.0.0-B03
/*
 * Copyright (c) 1998, 2018 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 v. 2.0 which is available at
 * http://www.eclipse.org/legal/epl-2.0,
 * or the Eclipse Distribution License v. 1.0 which is available at
 * http://www.eclipse.org/org/documents/edl-v10.php.
 *
 * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
 */

// Contributors:
//     dclarke, mnorman - Dynamic Persistence
//       http://wiki.eclipse.org/EclipseLink/Development/Dynamic
//       (https://bugs.eclipse.org/bugs/show_bug.cgi?id=200045)
//
package org.eclipse.persistence.dynamic;

//EclipseLink imports
import org.eclipse.persistence.exceptions.DynamicException;

/**
 * DynamicEntity is the public interface for dealing with dynamic persistent objects.
 * 
 * The purpose of dynamic persistent objects is to enable (simple) data access when only mapping
 * information is available 

 * and no concrete Java model is present (specifically, no .class files .)
 * 

 * Applications using DynamicEntity's can access the persistent state using property names
 * which correspond 

 * to the mapped attributes in the underlying EclipseLink descriptors.
 * For properties mapped to containers ({@link java.util.Collection Collection},

 * {@link java.util.Map Map}, etc.), the property is retrieved then the resulting container can
 * be manipulated.
 * 
 *     ...
 *     DynamicEntity de = ...; // retrieve from database
 *     Collection<String> myListOfGroups = de.<Collection<String>>get("myListOfGroups");
 *     if (!myListOfGroups.isEmpty()) {
 *        myListOfGroups.add("FabFour");
 *     }
 * 
 * To discover meta-data about a DynamicEntity's properties, see the {@link DynamicHelper} class
 *
 * @author dclarke, mnorman
 * @since EclipseLink 1.2
 */
public interface DynamicEntity {

    /**
     * Return the persistence value for the given property as the specified type.
     * In the case of relationships, this call will populate lazy-loaded relationships
     *
     * @param 
     *      generic type of the property (if not provided, assume Object).
     *      If the property cannot be cast to the specific type, a {@link DynamicException}will be thrown.
     * @param
     *      propertyName the name of a mapped property
     *      If the property cannot be found, a {@link DynamicException} will be thrown.
     * @throws
     *      DynamicException
     * @return
     *      persistent value or relationship container of the specified type
     */
    public  T get(String propertyName) throws DynamicException;

    /**
     * Set the persistence value for the given property to the specified value
     *
     * @param
     *      propertyName the name of a mapped property
     *      If the property cannot be found, a {@link DynamicException} will be thrown.
     * @param
     *      value the specified object
     * @throws
     *      DynamicException
     * @return
     *      the same DynamicEntity instance
     */
    public DynamicEntity set(String propertyName, Object value) throws DynamicException;

    /**
     * Discover if a property has a persistent value
     *
     * @param
     *      propertyName the name of a mapped property
     *      If the property cannot be found, a {@link DynamicException} will be thrown.
     * @return
     *      true if the property has been set
     * @throws
     *      DynamicException
     */
    public boolean isSet(String propertyName) throws DynamicException;

}