redora.api.PersistableList Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of api Show documentation
There is a newer version: 1.9.2
/*
 * Copyright 2009-2010 Nanjing RedOrange ltd (http://www.red-orange.cn)
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package redora.api;

import org.jetbrains.annotations.NotNull;
import org.jetbrains.annotations.Nullable;

import java.util.List;
import java.util.Set;

/**
 * PersistableList is a List used for parent / child one to many relations. Beside
 * all List and Collection methods, PersistableList adds some convenience methods
 * specific for the use of Persistable objects.
 * When you try to use classes that do not implement Persistable you will
 * get ClassCastExceptions.
 * 

 * The PersistentList implementation will do some under water housekeeping to add
 * and remove objects in the set into persistence. For example remove object
 * will be marked for deletion in the database (getRemovedObjcts()), adding new
 * object is simplified with:

 * PersistableObject o = insert(new PersistableObject());. This method will
 * create the new object and return an handle to the new object.
 *
 * @param  The Persistable pojos in this collection
 * @author Nanjing RedOrange (http://www.red-orange.cn)
 * @see redora.api.Persistable
 */
public interface PersistableList extends List {

    /**
     * Convenience method. Inserts a new object to the set and returns this
     * object. The object is not persisted and does not have an id.
     * @param e Usually a newly instantiated e
     * @return The given e
     */
    @NotNull
    abstract E insert(@NotNull E e);

    /**
     * Redora method. Removed objects are recorded
     * so Redora knows what objects should be removed
     * when the set is persisted.
     * After persisting, this set is set to empty.
     * @return Empty or filled list
     */
    @NotNull
    abstract List getRemovedObjects();

    /**
     * Elements added to this collection are add to this list until the collection
     * is persisted. The object can be new (id == null) or it can already have existed.
     * @return Empty or filled list with added objects
     */
    @NotNull
    abstract List getAddedObjects();

    /**
     * Redora method. True when the set is retrieved from the
     * database (lazy loading) or when the parent object is new.
     */
    abstract boolean isRetrieved();

    /** 
     * Redora method. Sets retrieved to true and purges all house keeping lists.
     * This method is invoked after filling the collection with data from the database
     * and after a persist.
     */
    abstract void reset();

    /**
     * Indicates if any member is added, removed or changed.
     * 'Sees' also changes in collections contained by members of this collection.
     * @return True if something is to be persisted in this collection
     */
    abstract boolean isDirty(@Nullable Set ignore);

   /** @return A set of cloned members of this set. */
    PersistableList clone(int depth);
}