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
The newest version!
/*
 * Copyright (c) 1998, 2024 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;

/**
 * {@code 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 {@code .class} files.)
 * 
 * Applications using {@code 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.
 * {@snippet :
 *  DynamicEntity de = ...; // retrieve from database
 *  Collection myListOfGroups = de.>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.
     * @return
     *      persistent value or relationship container of the specified type
     */
     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
     * @return
     *      the same DynamicEntity instance
     */
    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
     */
    boolean isSet(String propertyName) throws DynamicException;

}