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.applib.annotation.When;
023import org.apache.isis.applib.annotation.Where;
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.InteractionContextType;
028import org.apache.isis.core.metamodel.consent.InteractionInvocationMethod;
029import org.apache.isis.core.metamodel.facets.hide.HiddenFacet;
030import org.apache.isis.core.metamodel.interactions.AccessContext;
031import org.apache.isis.core.metamodel.interactions.InteractionContext;
032import org.apache.isis.core.metamodel.interactions.UsabilityContext;
033import org.apache.isis.core.metamodel.interactions.VisibilityContext;
034
035/**
036 * Provides reflective access to an action or a field on a domain object.
037 */
038public interface ObjectMember extends ObjectFeature {
039
040    // /////////////////////////////////////////////////////////////
041    // Name, Description, Help (convenience for facets)
042    // /////////////////////////////////////////////////////////////
043
044    /**
045     * Return the help text for this member - the field or action - to
046     * complement the description.
047     * 
048     * @see #getDescription()
049     */
050    String getHelp();
051
052    // /////////////////////////////////////////////////////////////
053    // Hidden (or visible)
054    // /////////////////////////////////////////////////////////////
055
056    /**
057     * When the member is always hidden.
058     * 
059     * <p>
060     * Determined as per the {@link HiddenFacet} being present and 
061     * {@link HiddenFacet#when()} returning {@link When#ALWAYS}, and
062     * {@link HiddenFacet#where()} returning {@link When#ANYWHERE}.
063     */
064    boolean isAlwaysHidden();
065
066    /**
067     * Create an {@link InteractionContext} to represent an attempt to view this
068     * member (that is, to check if it is visible or not).
069     * 
070     * <p>
071     * Typically it is easier to just call
072     * {@link #isVisible(AuthenticationSession, ObjectAdapter, Where)} or
073     * {@link #isVisibleResult(AuthenticationSession, ObjectAdapter)}; this is
074     * provided as API for symmetry with interactions (such as
075     * {@link AccessContext} accesses) have no corresponding vetoing methods.
076     */
077    VisibilityContext<?> createVisibleInteractionContext(AuthenticationSession session, InteractionInvocationMethod invocationMethod, ObjectAdapter targetObjectAdapter, Where where);
078
079    /**
080     * Determines if this member is visible, represented as a {@link Consent}.
081     * @param target
082     *            may be <tt>null</tt> if just checking for authorization.
083     * @param where 
084     *            the member is being rendered in the UI
085     * @see #isVisibleResult(AuthenticationSession, ObjectAdapter)
086     */
087    Consent isVisible(AuthenticationSession session, ObjectAdapter target, Where where);
088
089    // /////////////////////////////////////////////////////////////
090    // Disabled (or enabled)
091    // /////////////////////////////////////////////////////////////
092
093    /**
094     * Create an {@link InteractionContext} to represent an attempt to
095     * {@link InteractionContextType#MEMBER_USABLE use this member} (that is, to
096     * check if it is usable or not).
097     * 
098     * <p>
099     * Typically it is easier to just call
100     * {@link #isUsable(AuthenticationSession, ObjectAdapter, Where)} or
101     * {@link #isUsableResult(AuthenticationSession, ObjectAdapter)}; this is
102     * provided as API for symmetry with interactions (such as
103     * {@link AccessContext} accesses) have no corresponding vetoing methods.
104     */
105    UsabilityContext<?> createUsableInteractionContext(AuthenticationSession session, InteractionInvocationMethod invocationMethod, ObjectAdapter target, Where where);
106
107    /**
108     * Determines whether this member is usable, represented as a
109     * {@link Consent}.
110     * @param target
111     *            may be <tt>null</tt> if just checking for authorization.
112     * @param where 
113     *            the member is being rendered in the UI
114     * 
115     * @see #isUsableResult(AuthenticationSession, ObjectAdapter)
116     */
117    Consent isUsable(AuthenticationSession session, ObjectAdapter target, Where where);
118
119    // /////////////////////////////////////////////////////////////
120    // isAssociation, isAction
121    // /////////////////////////////////////////////////////////////
122
123    /**
124     * Whether this member represents a {@link ObjectAssociation}.
125     * 
126     * <p>
127     * If so, can be safely downcast to {@link ObjectAssociation}.
128     */
129    boolean isPropertyOrCollection();
130
131    /**
132     * Whether this member represents a {@link OneToManyAssociation}.
133     * 
134     * <p>
135     * If so, can be safely downcast to {@link OneToManyAssociation}.
136     */
137    boolean isOneToManyAssociation();
138
139    /**
140     * Whether this member represents a {@link OneToOneAssociation}.
141     * 
142     * <p>
143     * If so, can be safely downcast to {@link OneToOneAssociation}.
144     */
145    boolean isOneToOneAssociation();
146
147    /**
148     * Whether this member represents a {@link ObjectAction}.
149     * 
150     * <p>
151     * If so, can be safely downcast to {@link ObjectAction}.
152     */
153    boolean isAction();
154
155    // /////////////////////////////////////////////////////////////
156    // Debugging
157    // /////////////////////////////////////////////////////////////
158
159    String debugData();
160
161}