001    package org.apache.turbine.modules.screens;
002    
003    /*
004     * Licensed to the Apache Software Foundation (ASF) under one
005     * or more contributor license agreements.  See the NOTICE file
006     * distributed with this work for additional information
007     * regarding copyright ownership.  The ASF licenses this file
008     * to you under the Apache License, Version 2.0 (the
009     * "License"); you may not use this file except in compliance
010     * with the License.  You may obtain a copy of the License at
011     *
012     *   http://www.apache.org/licenses/LICENSE-2.0
013     *
014     * Unless required by applicable law or agreed to in writing,
015     * software distributed under the License is distributed on an
016     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017     * KIND, either express or implied.  See the License for the
018     * specific language governing permissions and limitations
019     * under the License.
020     */
021    
022    import org.apache.turbine.pipeline.PipelineData;
023    import org.apache.turbine.util.RunData;
024    
025    /**
026     * An extension to JSONScreen that performs a Security Check before invoking
027     * doBuildTemplate().  You should extend this class and add the specific
028     * security check needed.  If you have a number of screens that need to perform
029     * the same check, you could make a base screen by extending this class and
030     * implementing the isAuthorized().  Then each screen that needs to perform the
031     * same check could extend your base screen.
032     * 
033     * <p>Typically you would extend this class and override the doOutput() method
034     * to use TurbineJsonRpc to register the POJOs that will provide the functions
035     * you are making available via JSON-RPC.  Use JSONScreen if you <p>do not</b>
036     * need the user to be logged in prior to executing the functions you provide.
037     *
038     * <p>Here is an example from a superclass:
039     * <code>
040     * public void doOutput(RunData data) throws Exception
041     * {
042     *     User user = data.getUser();
043     *
044     *     MySecureJsonFunctions myFunctions
045     *             = new MySecureJsonFunctions(user.getName());
046     *
047     *     // Session specific
048     *     TurbineJsonRpc.registerObject(data.getSession(), "myFunctions", myFunctions);
049     *
050     *     // Global
051     *     //TurbineJsonRpc.registerObjectGlobal("testGlobal", testObject);
052     *
053     *     super.doOutput(data);
054     * }
055     * </code>
056     * 
057     * <p>The class MyFunctions would be something like:
058     * <code>
059     * public class MySecureJsonFunctions
060     * {
061     *     private final String name;
062     *
063     *     public MySecureJsonFunctions(String name)
064     *     {
065     *         this.name = name;
066     *     }
067     *
068     *     private String getName(String clientParameter)
069     *     {
070     *         return "Client " + clientParameter + " says Hello World to " + name;
071     *     }
072     * }
073     * </code>
074     *
075     * @author <a href="mailto:seade@policypoint.net">Scott Eade</a>
076     * @version $Id: JSONSecureScreen.java 958672 2010-06-28 18:42:04Z tv $
077     */
078    public abstract class JSONSecureScreen extends JSONScreen
079    {
080        /**
081         * This method overrides the method in JSONScreen to perform a security
082         * check prior to producing the output.
083         *
084         * @param data Turbine information.
085         * @exception Exception, a generic exception.
086         * @deprecated Use PipelineData version instead.
087         */
088        protected void doOutput(RunData data) throws Exception
089        {
090            if (isAuthorized(data))
091            {
092                super.doOutput(data);
093            }
094        }
095    
096        /**
097         * Override this method to perform the necessary security checks.
098         *
099         * @param data Turbine information.
100         * @return <code>true</code> if the user is authorized to access the screen.
101         * @exception Exception A generic exception.
102         * @deprecated Use PipelineData version instead.
103         */
104        protected abstract boolean isAuthorized(RunData data)
105                throws Exception;
106    
107        /**
108         * This method overrides the method in JSONScreen to perform a security
109         * check prior to producing the output.
110         *
111         * @param pipelineData Turbine information.
112         * @exception Exception, a generic exception.
113         */
114        protected void doOutput(PipelineData pipelineData) throws Exception
115        {
116            if (isAuthorized(pipelineData))
117            {
118                super.doOutput(pipelineData);
119            }
120        }
121    
122        /**
123         * Override this method to perform the necessary security checks.
124         *
125         * @param pipelineData Turbine information.
126         * @return <code>true</code> if the user is authorized to access the screen.
127         * @exception Exception A generic exception.
128         */
129        protected abstract boolean isAuthorized(PipelineData pipelineData)
130                throws Exception;
131    }