001/*
002 *  Licensed to the Apache Software Foundation (ASF) under one
003 *  or more contributor license agreements.  See the NOTICE file
004 *  distributed with this work for additional information
005 *  regarding copyright ownership.  The ASF licenses this file
006 *  to you under the Apache License, Version 2.0 (the
007 *  "License"); you may not use this file except in compliance
008 *  with the License.  You may obtain a copy of the License at
009 *
010 *        http://www.apache.org/licenses/LICENSE-2.0
011 *
012 *  Unless required by applicable law or agreed to in writing,
013 *  software distributed under the License is distributed on an
014 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 *  KIND, either express or implied.  See the License for the
016 *  specific language governing permissions and limitations
017 *  under the License.
018 */
019
020package org.apache.isis.core.metamodel.spec.feature;
021
022import org.apache.isis.core.commons.authentication.AuthenticationSession;
023import org.apache.isis.core.metamodel.adapter.ObjectAdapter;
024import org.apache.isis.core.metamodel.consent.Consent;
025import org.apache.isis.core.metamodel.consent.InteractionInvocationMethod;
026import org.apache.isis.core.metamodel.interactions.AccessContext;
027import org.apache.isis.core.metamodel.interactions.InteractionContext;
028import org.apache.isis.core.metamodel.interactions.ValidityContext;
029
030public interface OneToManyAssociation extends ObjectAssociation, OneToManyFeature {
031
032    // /////////////////////////////////////////////////////////////
033    // add
034    // /////////////////////////////////////////////////////////////
035
036    /**
037     * Creates an {@link InteractionContext} that represents validation of a
038     * candidate object to be added to the collection.
039     * 
040     * <p>
041     * Typically it is easier to just call
042     * {@link #isValidToAdd(ObjectAdapter, ObjectAdapter)} or
043     * {@link #isValidToAddResult(ObjectAdapter, ObjectAdapter)}; this is
044     * provided as API for symmetry with interactions (such as
045     * {@link AccessContext} accesses) have no corresponding vetoing methods.
046     */
047    public ValidityContext<?> createValidateAddInteractionContext(AuthenticationSession session, InteractionInvocationMethod invocationMethod, ObjectAdapter owningObjectAdapter, ObjectAdapter proposedObjectToAdd);
048
049    /**
050     * Determines if the specified element can be added to the collection field,
051     * represented as a {@link Consent}.
052     * 
053     * <p>
054     * If allowed the {@link #addElement(ObjectAdapter, ObjectAdapter) add}
055     * method can be called with the same parameters, .
056     * @see #isValidToAddResult(ObjectAdapter, ObjectAdapter)
057     */
058    Consent isValidToAdd(ObjectAdapter owningObjectAdapter, ObjectAdapter proposedObjectToAdd);
059
060    /**
061     * Add the specified element to this collection field in the specified
062     * object.
063     */
064    void addElement(ObjectAdapter owningObjectAdapter, ObjectAdapter objectToAdd);
065
066    // /////////////////////////////////////////////////////////////
067    // remove
068    // /////////////////////////////////////////////////////////////
069
070    /**
071     * Creates an {@link InteractionContext} that represents validation of a
072     * candidate object to be removed from the collection.
073     * 
074     * <p>
075     * Typically it is easier to just call
076     * {@link #isValidToAdd(ObjectAdapter, ObjectAdapter)} or
077     * {@link #isValidToAddResult(ObjectAdapter, ObjectAdapter)}; this is
078     * provided as API for symmetry with interactions (such as
079     * {@link AccessContext} accesses) have no corresponding vetoing methods.
080     */
081    ValidityContext<?> createValidateRemoveInteractionContext(AuthenticationSession session, InteractionInvocationMethod invocationMethod, ObjectAdapter owningObjectAdapter, ObjectAdapter proposedObjectToRemove);
082
083    /**
084     * Determines if the specified element can be removed from the collection
085     * field, represented as a {@link Consent}.
086     * 
087     * <p>
088     * If allowed the {@link #removeElement(ObjectAdapter, ObjectAdapter)
089     * remove} method can be called with the same parameters, .
090     * 
091     * @see #removeElement(ObjectAdapter, ObjectAdapter)
092     * @see #isValidToAddResult(ObjectAdapter, ObjectAdapter)
093     */
094    Consent isValidToRemove(ObjectAdapter owningObjectAdapter, ObjectAdapter proposedObjectToRemove);
095
096    /**
097     * Remove the specified element from this collection field in the specified
098     * object.
099     */
100    void removeElement(ObjectAdapter owningObjectAdapter, ObjectAdapter oObjectToRemove);
101
102    // /////////////////////////////////////////////////////////////
103    // clear
104    // /////////////////////////////////////////////////////////////
105
106    /**
107     * Remove all elements from this collection field in the specified object.
108     */
109    void clearCollection(ObjectAdapter inObject);
110
111}