View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *     http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17
    18  /*
    19   * InstanceCallbacks.java
    20   *
    21   */
    22
    23  package javax.jdo;
    24
    25  /** A <code>PersistenceCapable</code> class that provides callback methods for life
    26   * cycle events implements this interface.
    27   *
    28   * <P>For JDO 2.0, <code>InstanceCallbacks</code> has been refactored to extend
    29   * four other interfaces, without changing any of the methods or semantics.
    30   * This allows fine-grained control over callbacks, for
    31   * example to allow a class to implement the load callback without
    32   * implementing any of the other callbacks. For backward compatibility
    33   * with JDO 1.0, the <code>InstanceCallbacks</code> interface is preserved.
    34   *
    35   * <P>Classes which include non-persistent fields whose values depend
    36   * on the values of persistent fields require callbacks on specific
    37   * JDO instance life cycle events in order to correctly populate the
    38   * values in these fields.
    39   *
    40   * <P>The callbacks might also be used if the persistent instances
    41   * need to be put into the runtime infrastructure of the application.
    42   * For example, a persistent instance might notify other instances
    43   * on changes to state.  The persistent instance might be in a list of
    44   * managed instances. When the persistent instance is made hollow,
    45   * it can no longer generate change events, and the persistent
    46   * instance should be removed from the list of managed instances.
    47   *
    48   * <P>To implement this, the application programmer would implement
    49   * <code>jdoPostLoad</code> to put itself into the list of managed
    50   * instances, and implement <code>jdoPreClear</code> to remove itself from
    51   * the list. With JDO 1.0, the domain class would be declared to implement
    52   * <code>InstanceCallbacks</code>. With JDO 2.0, the domain class
    53   * would be declared to implement
    54   * <code>javax.jdo.listener.LoadCallback</code> and
    55   * <code>javax.jdo.listener.ClearCallback</code>.
    56   *
    57   * <P>Note that JDO does not manage the state of non-persistent
    58   * fields, and when a JDO instance transitions to hollow, JDO clears
    59   * the persistent fields.  It is the programmer's responsibility to
    60   * clear non-persistent fields so that garbage collection of
    61   * referred instances can occur.
    62   *
    63   * @since 1.0
    64   * @version 2.0
    65   */
    66  public interface InstanceCallbacks
    67      extends javax.jdo.listener.ClearCallback,
    68          javax.jdo.listener.DeleteCallback,
    69          javax.jdo.listener.LoadCallback,
    70          javax.jdo.listener.StoreCallback {
    71  }