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.filter.Filter;
023import org.apache.isis.applib.profiles.Localization;
024import org.apache.isis.core.commons.authentication.AuthenticationSession;
025import org.apache.isis.core.metamodel.adapter.ObjectAdapter;
026import org.apache.isis.core.metamodel.consent.InteractionInvocationMethod;
027import org.apache.isis.core.metamodel.facets.named.NamedFacet;
028import org.apache.isis.core.metamodel.interactions.ActionArgumentContext;
029
030/**
031 * Analogous to {@link ObjectAssociation}.
032 */
033public interface ObjectActionParameter extends ObjectFeature, CurrentHolder {
034
035    /**
036     * If true then can cast to a {@link OneToOneActionParameter}.
037     * 
038     * <p>
039     * Either this or {@link #isCollection()} will be true.
040     * 
041     * <p>
042     * Design note: modelled after {@link ObjectAssociation#isNotCollection()}
043     */
044    boolean isObject();
045
046    /**
047     * Only for symmetry with {@link ObjectAssociation}, however since the NOF
048     * does not support collections as actions all implementations should return
049     * <tt>false</tt>.
050     */
051    boolean isCollection();
052
053    /**
054     * Owning {@link ObjectAction}.
055     */
056    ObjectAction getAction();
057
058    /**
059     * Returns a flag indicating if it can be left unset when the action can be
060     * invoked.
061     */
062    boolean isOptional();
063
064    /**
065     * Returns the 0-based index to this parameter.
066     */
067    int getNumber();
068
069    /**
070     * Returns the name of this parameter.
071     * 
072     * <p>
073     * Because Java's reflection API does not allow us to access the code name
074     * of the parameter, we have to do figure out the name of the parameter
075     * ourselves:
076     * <ul>
077     * <li>If there is a {@link NamedFacet} associated with this parameter then
078     * we infer a name from this, eg "First Name" becomes "firstName".
079     * <li>Otherwise we use the type, eg "string".
080     * <li>If there is more than one parameter of the same type, then we use a
081     * numeric suffix (eg "string1", "string2"). Wrappers and primitives are
082     * considered to be the same type.
083     * </ul>
084     */
085    @Override
086    String getName();
087
088    ActionArgumentContext createProposedArgumentInteractionContext(AuthenticationSession session, InteractionInvocationMethod invocationMethod, ObjectAdapter targetObject, ObjectAdapter[] args, int position);
089
090
091    /**
092     * Whether there is an autoComplete provided (eg <tt>autoCompleteXxx</tt> supporting
093     * method) for the parameter.
094     */
095    boolean hasAutoComplete();
096    
097    /**
098     * Returns a list of possible references/values for this parameter, which the
099     * user can choose from, based on the input search argument.
100     */
101    ObjectAdapter[] getAutoComplete(ObjectAdapter adapter, String searchArg);
102
103    
104    
105    int getAutoCompleteMinLength();
106    /**
107     * Whether there are any choices provided (eg <tt>choicesXxx</tt> supporting
108     * method) for the parameter.
109     */
110    boolean hasChoices();
111
112    /**
113     * Returns a list of possible references/values for this parameter, which the
114     * user can choose from.
115     */
116    ObjectAdapter[] getChoices(ObjectAdapter adapter, final ObjectAdapter[] argumentsIfAvailable);
117
118
119    ObjectAdapter getDefault(ObjectAdapter adapter);
120
121    
122    /**
123     * Whether proposed value for this parameter is valid.
124     * 
125     * @param adapter
126     * @param proposedValue
127     * @return
128     */
129    String isValid(ObjectAdapter adapter, Object proposedValue, Localization localization);
130 
131
132    
133    public static class Filters {
134        private Filters(){}
135        
136        /**
137         * Filters only parameters that are for objects (ie 1:1 associations)
138         */
139        public static final Filter<ObjectActionParameter> PARAMETER_ASSOCIATIONS = new Filter<ObjectActionParameter>() {
140            @Override
141            public boolean accept(final ObjectActionParameter parameter) {
142                return parameter.getSpecification().isNotCollection();
143            }
144        };
145    }
146}