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 com.google.common.base.Function;
023
024import org.apache.isis.core.commons.authentication.AuthenticationSession;
025import org.apache.isis.core.metamodel.adapter.ObjectAdapter;
026import org.apache.isis.core.metamodel.consent.Consent;
027import org.apache.isis.core.metamodel.consent.InteractionInvocationMethod;
028import org.apache.isis.core.metamodel.interactions.AccessContext;
029import org.apache.isis.core.metamodel.interactions.InteractionContext;
030import org.apache.isis.core.metamodel.interactions.PropertyAccessContext;
031import org.apache.isis.core.metamodel.interactions.ValidityContext;
032import org.apache.isis.core.metamodel.spec.ObjectSpecification;
033
034/**
035 * Provides reflective access to a field on a domain object that is used to
036 * reference another domain object.
037 */
038public interface OneToOneAssociation extends ObjectAssociation, OneToOneFeature, MutableCurrentHolder {
039
040    /**
041     * Initialise this field in the specified object with the specified
042     * reference - this call should only affect the specified object, and not
043     * any related objects. It should also not be distributed. This is strictly
044     * for re-initialising the object and not specifying an association, which
045     * is only done once.
046     */
047    void initAssociation(ObjectAdapter inObject, ObjectAdapter associate);
048
049    /**
050     * Creates an {@link InteractionContext} that represents access to this
051     * property.
052     */
053    public PropertyAccessContext createAccessInteractionContext(AuthenticationSession session, InteractionInvocationMethod interactionMethod, ObjectAdapter targetObjectAdapter);
054
055    /**
056     * Creates an {@link InteractionContext} that represents validation of a
057     * proposed new value for the property.
058     * 
059     * <p>
060     * Typically it is easier to just call
061     * {@link #isAssociationValid(ObjectAdapter, ObjectAdapter)} or
062     * {@link #isAssociationValidResult(ObjectAdapter, ObjectAdapter)}; this is
063     * provided as API for symmetry with interactions (such as
064     * {@link AccessContext} accesses) have no corresponding vetoing methods.
065     */
066    public ValidityContext<?> createValidateInteractionContext(AuthenticationSession session, InteractionInvocationMethod interactionMethod, ObjectAdapter targetObjectAdapter, ObjectAdapter proposedValue);
067
068    /**
069     * Determines if the specified reference is valid for setting this field in
070     * the specified object, represented as a {@link Consent}.
071     */
072    Consent isAssociationValid(ObjectAdapter inObject, ObjectAdapter associate);
073
074    /**
075     * Set up the association represented by this field in the specified object
076     * with the specified reference - this call sets up the logical state of the
077     * object and might affect other objects that share this association (such
078     * as back-links or bidirectional association). To initialise a recreated
079     * object to this logical state the <code>initAssociation</code> method
080     * should be used on each of the objects.
081     * 
082     * @deprecated - see {@link #set(ObjectAdapter, ObjectAdapter)}
083     * @see #initAssociation(ObjectAdapter, ObjectAdapter)
084     */
085    @Deprecated
086    void setAssociation(ObjectAdapter inObject, ObjectAdapter associate);
087
088    /**
089     * Clear this reference field (make it <code>null</code>) in the specified
090     * object, and remove any association back-link.
091     * 
092     * @see #setAssociation(ObjectAdapter, ObjectAdapter)
093     * @deprecated - see {@link #set(ObjectAdapter, ObjectAdapter)}
094     */
095    @Deprecated
096    void clearAssociation(ObjectAdapter inObject);
097
098    
099    // //////////////////////////////////////////////////////
100    // Functions
101    // //////////////////////////////////////////////////////
102    
103    public static class Functions {
104        public static Function<String, OneToOneAssociation> fromId(final ObjectSpecification noSpec) {
105            return new Function<String, OneToOneAssociation>() {
106                @Override
107                public OneToOneAssociation apply(final String id) {
108                    return (OneToOneAssociation) noSpec.getAssociation(id);
109                }
110            };
111        }
112    }
113
114}