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