001    // Copyright 2004, 2005 The Apache Software Foundation
002    //
003    // Licensed under the Apache License, Version 2.0 (the "License");
004    // you may not use this file except in compliance with the License.
005    // You may obtain a copy of the License at
006    //
007    //     http://www.apache.org/licenses/LICENSE-2.0
008    //
009    // Unless required by applicable law or agreed to in writing, software
010    // distributed under the License is distributed on an "AS IS" BASIS,
011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012    // See the License for the specific language governing permissions and
013    // limitations under the License.
014    
015    package org.apache.tapestry.link;
016    
017    import java.util.Collection;
018    
019    import org.apache.tapestry.IActionListener;
020    import org.apache.tapestry.IDirect;
021    import org.apache.tapestry.IRequestCycle;
022    import org.apache.tapestry.IScript;
023    import org.apache.tapestry.engine.DirectServiceParameter;
024    import org.apache.tapestry.engine.IEngineService;
025    import org.apache.tapestry.engine.ILink;
026    import org.apache.tapestry.listener.ListenerInvoker;
027    
028    /**
029     * A component for creating a link using the direct service; used for actions that are not dependant
030     * on dynamic page state. [ <a href="../../../../../ComponentReference/DirectLink.html">Component
031     * Reference </a>]
032     * 
033     */
034    
035    public abstract class DirectLink extends AbstractLinkComponent implements IDirect
036    {
037        public abstract IActionListener getListener();
038    
039        /**
040         * Returns true if the stateful parameter is bound to a true value. If stateful is not bound,
041         * also returns the default, true.
042         */
043        
044        public abstract boolean isStateful();
045        
046        public ILink getLink(IRequestCycle cycle)
047        {
048            Object[] serviceParameters = constructServiceParameters(getParameters());
049            
050            DirectServiceParameter dsp = new DirectServiceParameter(this, serviceParameters);
051            
052            return getEngine().getLink(isStateful(), dsp);
053        }
054        
055        /**
056         * Converts a service parameters value to an array of objects. This is used by the
057         * {@link DirectLink},{@link ServiceLink}and {@link ExternalLink}components.
058         * 
059         * @param parameterValue
060         *            the input value which may be
061         *            <ul>
062         *              <li>null (returns null)
063         *              <li>An array of Object (returns the array)
064         *              <li>A {@link Collection}(returns an array of the values in the Collection})
065         *              <li>A single object (returns the object as a single-element array)
066         *            </ul>
067         * @return An array representation of the input object.
068         * @since 2.2
069         */
070    
071        public static Object[] constructServiceParameters(Object parameterValue)
072        {
073            if (parameterValue == null)
074                return null;
075    
076            if (parameterValue instanceof Object[])
077                return (Object[]) parameterValue;
078    
079            if (parameterValue instanceof Collection)
080                return ((Collection) parameterValue).toArray();
081    
082            return new Object[] { parameterValue };
083        }
084    
085        /**
086         * Invoked by the direct service to trigger the application-specific action by notifying the
087         * {@link IActionListener listener}. If the listener parameter is not bound, attempt to locate
088         * an implicit listener named by the capitalized component id, prefixed by "do".
089         * 
090         * @throws org.apache.tapestry.StaleSessionException
091         *             if the component is stateful, and the session is new.
092         */
093    
094        public void trigger(IRequestCycle cycle)
095        {
096            IActionListener listener = getListener();
097    
098            if (listener == null)
099                    listener = getContainer().getListeners().getImplicitListener(this);
100    
101            getListenerInvoker().invokeListener(listener, this, cycle);
102        }
103    
104        /** @since 2.2 * */
105    
106        public abstract Object getParameters();
107    
108        /**
109         * Injected.
110         * 
111         * @since 4.0
112         */
113    
114        public abstract ListenerInvoker getListenerInvoker();
115        
116        /**
117         * Injected.
118         * 
119         * @since 4.1
120         */
121        public abstract IEngineService getEngine();
122        
123        /**
124         * Injected.
125         * @return The script to process asynchronous connection hookups.
126         */
127        public abstract IScript getScript();
128    }