001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more contributor license
003 * agreements. See the NOTICE file distributed with this work for additional information regarding
004 * copyright ownership. The ASF licenses this file to you under the Apache License, Version 2.0 (the
005 * "License"); you may not use this file except in compliance with the License. You may obtain a
006 * copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable
007 * law or agreed to in writing, software distributed under the License is distributed on an "AS IS"
008 * BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License
009 * for the specific language governing permissions and limitations under the License.
010 */
011 package javax.portlet.faces;
012
013 import java.io.IOException;
014
015 import javax.faces.context.FacesContext;
016 import javax.portlet.Event;
017 import javax.portlet.faces.event.EventNavigationResult;
018
019
020 /**
021 * The <code>BridgeWriteBehindResponse</code> interface defines the api the bridge relies
022 * on to acquire the buffered JSP output from the response(Wrapper) used to handle the Faces
023 * implementation dependent writeBehindResponse methodlogy/interface.<p>
024 *
025 * Note: the Portlet 1.0 Bridge relied on Portlet 1.0 which didn't support response wrappers.
026 * In that version the writeBehindResponse behavior is provided in a Servlet ResponseWrapper inserted
027 * in a Servlet filter set up to be called on included JSPs. In Portlet 2.0 Bridge this behavior can
028 * now be implemented directly in a Portlet ResponseWrapper which can then be registered for use with the bridge.
029 * So that the bridge recognizes and use this support, such wrappers must implement this interface.<p>
030 *
031 * Implementations must be one of the Portlet 2.0 <code>ResponseWrappers</code> and have a null constructor that utilizes
032 * <code>FacesContext.getCurrentInstance().getExternalContext().getResponse()</code>
033 * to acquire the response to be wrapped.
034 */
035
036 public interface BridgeWriteBehindResponse
037 {
038 /**
039 * Called by the bridge after dispatching is complete to determine whether the
040 * JSP AfterViewContent was written as chars (written via a <code>PrintWriter</code>
041 *
042 *
043 * @return <code>true</code> if the response (buffer) is represented as chars
044 * written via the <code>PrintWriter</code>, false otherwise.
045 */
046 public boolean isChars();
047
048 /**
049 * Called by the bridge after dispatching is complete to acquire the AfterJSPContent
050 * when the response has been written as characters. The bridge writes this buffer
051 * to the (real) response.
052 *
053 * @return the response as a char[].
054 */
055 public char[] getChars();
056
057 /**
058 * Called by the bridge after dispatching is complete to determine whether the
059 * JSP AfterViewContent was written as bytes (written via an <code>OutputStream</code>
060 *
061 *
062 * @return <code>true</code> if the response (buffer) is represented as bytes
063 * written via the <code>OutputStream</code>, false otherwise.
064 */
065 public boolean isBytes();
066
067 /**
068 * Called by the bridge after dispatching is complete to acquire the AfterJSPContent
069 * when the response has been written as bytes. The bridge writes this buffer
070 * to the (real) response.
071 *
072 * @return the response as a byte[].
073 */
074 public byte[] getBytes();
075
076 /**
077 * Called by the bridge after dispatching to flush the current buffered content to the wrapped
078 * response (this could be a Servlet or Portlet response). This is done in a situation where
079 * we aren't supporting writeBehind behavior. We stil use a wrapped/buffered response because we use
080 * dispatch.forward which in many environments closes the writer at the end of the forward. If not
081 * wrapped, not further writing to the output would be feasible.
082 * @throws IOException if content cannot be written
083 */
084 public void flushMarkupToWrappedResponse()
085 throws IOException;
086
087 /**
088 * Called by the bridge to detect whether this response actively participated
089 * in the Faces writeBehind support and hence has data that should be written
090 * after the View is rendered. Typically, this method will return <code>true</code>
091 * if the Faces write behind implementation specific flush api has been called
092 * on this response, otherwise <code>false</code>
093 *
094 * @return an indication of whether the response actually particpated in the writeBehind mechanism.
095 */
096 public boolean hasFacesWriteBehindMarkup();
097 }