cdmlib-persistence/src/main/java/eu/etaxonomy/cdm/persistence/dao/IBeanInitializer.java

   1 // $Id$
   2 /**
   3 * Copyright (C) 2009 EDIT
   4 * European Distributed Institute of Taxonomy
   5 * http://www.e-taxonomy.eu
   6 *
   7 * The contents of this file are subject to the Mozilla Public License Version 1.1
   8 * See LICENSE.TXT at the top of this package for the full license terms.
   9 */
  10 package eu.etaxonomy.cdm.persistence.dao;
  11
  12 import java.util.Collection;
  13 import java.util.List;
  14
  15 import eu.etaxonomy.cdm.model.name.TaxonNameBase;
  16 import eu.etaxonomy.cdm.model.taxon.Taxon;
  17
  18 /**
  19  * @author a.kohlbecker
  20  * @date 25.03.2009
  21  *
  22  */
  23 public interface IBeanInitializer {
  24
  25     /**
  26      * Wildcard for initializing all *ToOne relations of a <code>bean</code>.
  27      */
  28     public static final String LOAD_2ONE_WILDCARD = "$";
  29
  30     /**
  31      * Wildcard for initializing all *ToOne and all *ToMany relations of a <code>bean</code>.
  32      */
  33     public static final String LOAD_2ONE_2MANY_WILDCARD = "*";
  34
  35     /**
  36      * Initializes all *ToOne relations of the <code>bean</code>.
  37      *
  38      * @param bean
  39      */
  40     public void load(Object bean);
  41
  42     /**
  43      * Initializes all *ToOne and all *ToMany relations of the <code>bean</code>.
  44      *
  45      * @param bean
  46      */
  47     public void loadFully(Object bean);
  48
  49     /**
  50      * Allows more fine grained initialization not only of the root bean
  51      * identified by its <code>uuid</code> but also of specific paths of
  52      * the object graph. The sub graph to initialize may be defined in the
  53      * <code>propertyPaths</code> parameter as list of paths all starting at the
  54      * root bean.
  55      * <p>
  56      * You can use wildcards <code>*</code> {@link LOAD_2ONE_2MANY_WILDCARD}
  57      * and <code>$</code> {@link LOAD_2ONE_WILDCARD} for initializing
  58      * all *ToOne and all *ToMany relations of a bean.
  59      * NOTE: A wildcard subsequently terminates its property path.
  60      * <p>
  61      * <b>Example:</b> Assuming <code>cdmEntity</code> is a {@link Taxon}
  62      * instance the following <code>propertyPaths</code> can be used for
  63      * initializing bean properties of this instance. It is possible to
  64      * initialized nested properties of properties with unlimited depth.
  65      * <ul>
  66      * <li><code>name</code>: initializes {@link Taxon#getName()}</li>
  67      * <li><code>name.rank</code>: initializes {@link Taxon#getName()}.{@link TaxonNameBase#getRank() getRank()}</li>
  68      * <li><code>name.$</code>: initializes all *ToOne relations of the {@link Taxon#getName()}</li>
  69      * </ul>
  70      *
  71      * @param bean
  72      * @param propertyPaths
  73      *            a List of property names
  74      */
  75     public void initialize(Object bean,  List<String> propertyPaths);
  76
  77     /**
  78      * Initializes the entities given in the bean list according to the given
  79      * <code>propertyPaths</code>.
  80      *
  81      * @param beanList
  82      * @param propertyPaths
  83      * @return
  84      */
  85     public <C extends Collection<?>> C initializeAll(C list,  List<String> propertyPaths);
  86
  87     /**
  88      * Initialize the the proxy, unwrap the target object and return it.
  89      *
  90      * @param proxy
  91      *            the proxy to initialize may wrap a single bean or a collection
  92      * @return the unwrapped target object
  93      */
  94     public Object initializeInstance(Object proxy);
  95
  96
  97     /*TODO implement:
  98     public void loadBy(UUID uuid);
  99     public void loadFullyByUuid(UUID uuid);*/
 100
 101 }