org.eclipse.persistence.sdo.ValueStore 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, 2021 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:
//     Oracle - initial API and implementation from Oracle TopLink
package org.eclipse.persistence.sdo;

import commonj.sdo.DataObject;
import commonj.sdo.Property;

/**
 * Purpose
 *  The ValueStore interface exposes the property model in SDO to pluggable implementers
 *   that wish to wrap their object model in the SDO API.
 *   
 *   The ValueStore interface exposes the properties Map in SDODataObject to extension or replacement.
 *   The implementing class must override or extend the get/set/isSet/unset ValueStore functions so that
 *   any calls routed through the SDO API are routed through to the underlying Data-Model that ValueStore wraps.
 *   

 *   Possible implementers must maintain DataObject integrity
 *   which includes containment and changeSummary.
 *
 *   
Setup:

 *   Before using the ValueStore interface the type tree must be defined by loading in the
 *   XSD schema file that matches the plugged in model if using dynamic classes.
 * 

 * The ValueStore interface enables 3rd party implementers of the SDO API to plug-in their
 * object model in place of the default SDO DataObject interface.
 * The Map like functions set/get and the List like functions isSet/unset are left to the
 * implementation to maintain.

 * It is the responsibility of the implementation to handle read or read/write capability against the
 * underlying object model.  Any access or modification of the pluggable object model done
 * outside of this interface may destabilize the ValueStore state.
 * 
 */
public interface ValueStore {

    /*
     07/28/06 - POJOValueStore creation
     08/21/06 - refactor from implementing ValueStore to implementing Pluggable
     08/24/06 - move Pluggable.set() functionality to HashMap.put() - remove Pluggable interface
                                    - ATG performance updates refactor requires non-Map ValueStore interface
     09/04/06 - split POJO read/write functionality into subclasses
     11/28/06 - For custom implementations of ValueStore that utilize
                                             any of the helpers in HelperContext - be aware that
                                             a HelperContext instance must be passed in via
                                             custom constructor or the default static context will be used
     02/01/07 - add copy() function as part of SDOChangeSummary.undoChanges()
     */

    Object getDeclaredProperty(int propertyIndex);

    Object getOpenContentProperty(Property property);

    void setDeclaredProperty(int propertyIndex, Object value);

    void setOpenContentProperty(Property property, Object value);

    void setManyProperty(Property propertyName, Object value);

    boolean isSetDeclaredProperty(int propertyIndex);

    boolean isSetOpenContentProperty(Property property);

    void unsetDeclaredProperty(int propertyIndex);

    void unsetOpenContentProperty(Property property);

    /**
     * Perform any post-instantiation integrity operations that could not be done during
     * ValueStore creation.

     * Since the dataObject reference passed in may be bidirectional or self-referencing
     * - we cannot set this variable until the dataObject itself is finished instantiation
     * - hence the 2-step initialization.
     *
     * @param dataObject
     */
    void initialize(DataObject dataObject);

    /**
     * Get a shallow copy of the original ValueStore.
     * Changes made to the copy must not impact the original ValueStore
     * @return ValueStore
     */
    ValueStore copy();
}