1 /* ==================================================================== 2 * The Jcorporate Apache Style Software License, Version 1.2 05-07-2002 3 * 4 * Copyright (c) 1995-2002 Jcorporate Ltd. All rights reserved. 5 * 6 * Redistribution and use in source and binary forms, with or without 7 * modification, are permitted provided that the following conditions 8 * are met: 9 * 10 * 1. Redistributions of source code must retain the above copyright 11 * notice, this list of conditions and the following disclaimer. 12 * 13 * 2. Redistributions in binary form must reproduce the above copyright 14 * notice, this list of conditions and the following disclaimer in 15 * the documentation and/or other materials provided with the 16 * distribution. 17 * 18 * 3. The end-user documentation included with the redistribution, 19 * if any, must include the following acknowledgment: 20 * "This product includes software developed by Jcorporate Ltd. 21 * (http://www.jcorporate.com/)." 22 * Alternately, this acknowledgment may appear in the software itself, 23 * if and wherever such third-party acknowledgments normally appear. 24 * 25 * 4. "Jcorporate" and product names such as "Expresso" must 26 * not be used to endorse or promote products derived from this 27 * software without prior written permission. For written permission, 28 * please contact info@jcorporate.com. 29 * 30 * 5. Products derived from this software may not be called "Expresso", 31 * or other Jcorporate product names; nor may "Expresso" or other 32 * Jcorporate product names appear in their name, without prior 33 * written permission of Jcorporate Ltd. 34 * 35 * 6. No product derived from this software may compete in the same 36 * market space, i.e. framework, without prior written permission 37 * of Jcorporate Ltd. For written permission, please contact 38 * partners@jcorporate.com. 39 * 40 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED 41 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 42 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 43 * DISCLAIMED. IN NO EVENT SHALL JCORPORATE LTD OR ITS CONTRIBUTORS 44 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 45 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED 46 * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF 47 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 48 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 49 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT 50 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 51 * SUCH DAMAGE. 52 * ==================================================================== 53 * 54 * This software consists of voluntary contributions made by many 55 * individuals on behalf of the Jcorporate Ltd. Contributions back 56 * to the project(s) are encouraged when you make modifications. 57 * Please send them to support@jcorporate.com. For more information 58 * on Jcorporate Ltd. and its products, please see 59 * <http://www.jcorporate.com/>. 60 * 61 * Portions of this software are based upon other open source 62 * products and are subject to their respective licenses. 63 */ 64 65 package com.jcorporate.expresso.core.dataobjects; 66 67 /** 68 * Nestable indicates that the derived class includes nested data objects. 69 * <p>While 70 * the dataobject 'cluster' should be able to be acted on as a single unit, 71 * once in a while, it is necessary to get at the internal or "nested" 72 * data objects. </p> 73 * <p>An example of the Nestable usage is in 74 * <code>com.jcorporate.expresso.services.controller.dbmaint.ViewBlob</code> 75 * in conjunction with a 76 * <code>com.jcorporate.expresso.cores.dataobjects.jdbc.JoinedDataObject</code>. 77 * The ViewBlob routine needs to get to the low-level JDBC data objects rather 78 * than operate on the join as a whole. Since JoinedDataObject implements the 79 * <code>Nestable</code> interface. It is then possible to work with the underlying 80 * JDBCDataObjects in the join. 81 * </p> 82 * 83 * @author Michael Rimov 84 */ 85 public interface NestableDataObject { 86 87 /** 88 * Retrieves a nested dataobject based upon the public field name that 89 * the DataObject publishes. For example, in JoinedDataObjects, the field 90 * name ""abcd.efgh" represents DataObject 'abcd', and field name 91 * 'efgh'. 92 * <p>The actual usage of the naming convention will differ from the, thus 93 * you'll need to use getMetaData().getFieldList() to get the names of the 94 * fields of a <code>Nestable</code> object to get a valid field Name</p> 95 * 96 * @param fieldName the full field name to get the nested data object. 97 * @return DataObject or possibly null. 98 * @throws IllegalArgumentException if the field name does not map to any 99 * DataObject 100 */ 101 public DataObject getNestedFromFieldName(String fieldName); 102 103 /** 104 * Often times, field names for the external interface will be different 105 * from the of a nested field name in a data object. Use this function 106 * to get the internal field name for the DataObject returned by 107 * <code>getNestedFromFieldName()</code> 108 * 109 * @param fieldName The external name of the field 110 * @return java.lang.String, the field corresponding to the field name 111 * of the data object 112 * @throws IllegalArgumentException if the given field name cannot map 113 * to a field. 114 */ 115 public String getFieldFromNestedName(String fieldName); 116 117 /** 118 * Retrieve an array of all nested data objects. May be empty if there 119 * are no nested data objects. Ordering is undefined by this function. 120 * 121 * @return Array of DataObjects. Should never return null. 122 */ 123 public DataObject[] getAllNested(); 124 125 126 }