001 /* 002 Copyright (C) 2002 Renaud Pawlak <renaud@aopsys.com> 003 004 This program is free software; you can redistribute it and/or modify 005 it under the terms of the GNU Lesser General Public License as 006 published by the Free Software Foundation; either version 2 of the 007 License, or (at your option) any later version. 008 009 This program is distributed in the hope that it will be useful, 010 but WITHOUT ANY WARRANTY; without even the implied warranty of 011 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 012 GNU Lesser General Public License for more details. 013 014 You should have received a copy of the GNU Lesser General Public License 015 along with this program; if not, write to the Free Software 016 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA */ 017 018 package org.objectweb.jac.aspects.integrity; 019 020 import org.objectweb.jac.core.rtti.CollectionItem; 021 import org.objectweb.jac.core.rtti.FieldItem; 022 import org.objectweb.jac.core.rtti.MethodItem; 023 024 public interface IntegrityConf { 025 026 /** 027 * Tells that the integrity aspect should maintain integrity 028 * between the roles of associations. 029 * 030 * <p>For instance, if you have a Customer class and an Order 031 * class:</p> 032 * 033 * <pre> 034 * ,----------. 1 n ,-------. 035 * | Customer |--------| Order | 036 * `----------' `-------' 037 * </pre> 038 * 039 * <p>You can declare an association made of Cutomer.orders and 040 * Order.customer, so that setting the cutomer of an order will 041 * automatically add this order in the customer's list of 042 * orders. And vice-versa.</p> 043 * 044 * @see org.objectweb.jac.core.rtti.RttiAC#declareAssociation(FieldItem,FieldItem) 045 */ 046 void updateAssociations(); 047 048 /** 049 * This method declares a repository collection. 050 * 051 * <p>When an object is added to a relation, it will be 052 * automatically added to the collection of the repository. 053 * 054 * @param repositoryName the JAC object's name of the repository 055 * @param collection the collection to add into (on the instance 056 * given as the first parameter) 057 * @param field objects that are set or added to this field are 058 * added to the repository */ 059 void declareRepository(String repositoryName, 060 CollectionItem collection, 061 FieldItem field); 062 063 /** 064 * <p>Declare a referential integrity contraint.</p> 065 * 066 * <p>When an object is removed from the target collection, it will 067 * be checked wether it can be allowed.</p> 068 * 069 * <p>Suppose you have Customer class and an Invoice class :</p> 070 * <pre> 071 * ,-----------. 1 * ,----------. 1 * ,---------. 072 * | Customers |-------| Customer |-----------| Invoice | 073 * `-----------' `----------' `---------' 074 * </pre> 075 * 076 * <p>You do not want to allow the removal of a customer from the 077 * Customers repository if there are invoices for that customer. So 078 * you would add the following constraint:</p> 079 * 080 * <code>declareConstraint Invoice.customer Customers.customers FORBIDDEN;</code> 081 * 082 * @param relation 083 * @param target the collection on which checking will occur on 084 * remove, or the reference on which checking will occur when 085 * setting another value. 086 * @param constraint the type of the constraint. It may be 087 * "DELETE_CASCADE" (delete the object holding the reference on the 088 * object to be deleted), "SET_NULL" (set the reference to null, or 089 * remove the object from the collection), FORBIDDEN" (raise an 090 * exception). 091 */ 092 void declareConstraint(FieldItem relation, 093 FieldItem target, String constraint); 094 095 /** 096 * Use this configuration method to add a precondition on a 097 * object's field. 098 * 099 * <p>It means that the initial value of the field will be tested 100 * with the added constraint and if it is not valid, it will be 101 * rejected.</p> 102 * 103 * <p>Constraint methods must return a Boolean that is Boolean.TRUE 104 * if the test has been validated (passed), Boolean.FALSE else. The 105 * class <code>org.objectweb.jac.aspects.integrity.GenericConditions</code> 106 * contains basic tests such as <code>forbiddenValues</code> or 107 * <code>authorizedValues</code>.</p> 108 * 109 * @param field the field to constrain 110 * @param constraint the constraint method used to check the 111 * field's value 112 * @param params the parameters passed to the contraint method 113 * @param errorMsg the error message displayed if the checking has 114 * not been passed 115 * 116 * @see #addPostCondition(FieldItem,MethodItem,Object[],String) 117 */ 118 void addPreCondition(FieldItem field, 119 MethodItem constraint, 120 Object[] params, 121 String errorMsg); 122 123 /** 124 * Use this configuration method to add a postcondition on a 125 * object's field. 126 * 127 * <p>It means that the final value of the field will be tested 128 * with the added constraint and if it is not valid, it will be 129 * rejected.</p> 130 * 131 * <p>Constraint methods must return a Boolean that is Boolean.TRUE 132 * if the test has been validated (passed), Boolean.FALSE else. The 133 * class <code>org.objectweb.jac.aspects.integrity.GenericConditions</code> 134 * contains basic tests such as <code>forbiddenValues</code> or 135 * <code>authorizedValues</code>.</p> 136 * 137 * @param field the field to constrain 138 * @param constraint the constraint method used to check the 139 * field's value 140 * @param params the parameters passed to the contraint method 141 * @param errorMsg the error message displayed if the checking has 142 * not been passed 143 * 144 * @see #addPreCondition(FieldItem,MethodItem,Object[],String) 145 */ 146 void addPostCondition(FieldItem field, 147 MethodItem constraint, 148 Object[] params, 149 String errorMsg); 150 151 } 152