com.caucho.portal.generic
Class PortletConnection

java.lang.Object
  com.caucho.portal.generic.PortletConnection

Direct Known Subclasses:

HttpPortletConnection

public abstract class PortletConnection
extends java.lang.Object

A PortletConnection is used to obtain Action and Render objects. For implementations that support only one portlet for each connection, the pattern of use is:

 Window window = ...;
 Portlet portlet = ...; 

 Action action = connection.getAction(window);

 if (action != null) {
   try {
      if (action.isTarget()) 
       action.processAction(portlet);
   } 
   finally { 
     action.finish(); 
   } 
 }
 
 Render render = connection.getRender(window);
 
 if (render != null) {
   try {
     render.render(portlet);
   } 
   finally { 
     render.finish(); 
   } 
 }

 

For implementations that support more than one portlet for each connection, each portlet is identified with a namespace. An optional Renderer is specified, it is used to obtain a Writer or OutputStream when the portlet requests it.

 Window window = ...;
 Portlet portlet = ...; 
 String namespace = "..."; 

 Action action = connection.getAction(window, namespace);

 if (action != null) {
   try {
     if (action.isTarget()) 
       action.processAction(portlet);
   } 
   finally { 
     action.finish(); 
   } 
 }
 
 Render render = connection.getRender(window, namespace);
 
 if (render != null) {
   try {
     render.render(portlet);
   } 
   finally { 
     render.finish(); 
   } 
 }

 

See Also:

getAction(PortletRequest), getRender(PortletRequest), Action, Render

Field Summary

static java.util.logging.Logger	log
static java.lang.String	PORTLET_CONNECTION Name of the request attribute that stores the connection

Constructor Summary

protected

PortletConnection()

Method Summary

abstract void	addProperty(java.lang.String name, java.lang.String value) Add a value to a property to be returned to the client.
abstract boolean	canGuaranteeConfidentiality() Return true if the connection can guarantee confidentiality (preventing reading while in transit).
abstract boolean	canGuaranteeIntegrity() Return true if the connection can guarantee integrity (preventing data tampering in the communication process).
void	checkForFailure() Throw an exception if an error was encountered when using this conneciton.
abstract java.lang.String	encodeURL(java.lang.String path) Encode a url with any special encoding needed by the protocol, for example by adding a sesison id.
void	finish()
abstract void	flushBuffer()
static Action	getAction(PortletRequest portletRequest) Return the Action that corresponds to the PortletRequest, or null if there is not a current Action or Connection.
Action	getAction(Window window, java.lang.String namespace) Get an Action for a namespace.
abstract java.lang.Object	getAttribute(java.lang.String name) Get an attribute for the current connection.
abstract java.util.Enumeration	getAttributeNames() Get a list of all attributes for the current connection.
abstract java.lang.String	getAuthType() Return the authentication scheme used for the current request.
abstract int	getBufferSize()
abstract java.lang.String	getCharacterEncoding()
abstract java.util.Set<java.lang.String>	getClientCharacterEncodings() Get the character encodings acceptable to the client.
abstract java.util.Set<java.lang.String>	getClientContentTypes() Get the content types acceptable to the client.
abstract java.util.Set<java.util.Locale>	getClientLocales() Get the locales acceptable to the client.
static PortletConnection	getConnection(PortletRequest portletRequest) Return the connection that corresponds to the PortletRequest
abstract java.lang.String	getContentType() Return the content type established with setContentType(), or null if setContentType() has not been called.
abstract java.lang.String	getContextPath() Return the path to the portal portion of the url that was used to make the request.
Action	getCurrentAction() Get the current Action object, established from a call to getRender().
Render	getCurrentRender() Get the current Render object, established from a call to getRender().
protected int	getExpirationCache() Used in derived classes during finish() to determine the maximum expires time for the connection, derived classes use this value to send an expires timeout to the client.
java.lang.String	getId() A unique identifier for this connection object, used for debugging
abstract java.util.Locale	getLocale() Return the Locale established with setLocale(), or null if setLocale() has not been called.
abstract java.io.OutputStream	getOutputStream()
Portal	getPortal()
static Portal	getPortal(PortletRequest portletRequest) Return the Portal that corresponds to the PortletRequest, or null if there is not a current Portal or Connection.
abstract PortletSession	getPortletSession(boolean create) Return a PortletSession for the current client, or null if one is not available.
abstract java.util.Enumeration	getProperties(java.lang.String propertyName) Return the values of the specified connection property as an array of Strings, null if the property was not provided by the request from the client.
abstract java.lang.String	getProperty(java.lang.String propertyName) Return the value of the specified connection property as a String, null if the property was not provided by the request from the client.
abstract java.util.Enumeration	getPropertyNames() Return the names of available properties for the connection.
abstract java.lang.String	getRemoteUser() Return the identity of the remote user, null if the identity has not been established.
static Render	getRender(PortletRequest portletRequest) Return the Render that corresponds to the PortletRequest, or null if there is not a current Render or Connection.
Render	getRender(Window window, java.lang.String namespace) Get a Render for a namespace.
abstract java.lang.String	getRequestedSessionId() Return the session id that was supplied by the client for the current request.
abstract java.lang.String	getScheme() Return the scheme portion of the url that was used to make the request.
abstract java.lang.String	getServerName() Return the host name portion of the url that was used to make the request.
abstract int	getServerPort() Return the port portion of the url that was used to make the request.
abstract java.lang.String	getSubmitCharacterEncoding() Return the name of the character encoding that will be used by the Reader obtained using #getReader, null if none.
abstract int	getSubmitContentLength() Return the length of of the data supplied as the "body" of the request, -1 if not known.
abstract java.lang.String	getSubmitContentType() Return the MIME type of the data supplied as the "body" of the request, null if not known.
abstract java.io.InputStream	getSubmitInputStream() Return the binary body of the current request.
abstract java.io.BufferedReader	getSubmitReader()
abstract java.security.Principal	getUserPrincipal() Return a Principal that contains the identity of the remote user, null if the identity has not been established.
abstract java.io.PrintWriter	getWriter()
abstract boolean	handleConstraintFailure(Constraint constraint, int failureCode) Handle a constraint failure by sending some response to the client.
abstract boolean	handleException(java.lang.Exception exception) Handle an exception by sending some response to the client.
abstract boolean	isCommitted()
boolean	isConnectionFailed() A connection fails if an unrecoverable error occurs.
protected boolean	isPrivate() Used in derived classes during finish() to determine if the response is private
abstract boolean	isRequestedSessionIdValid() Return true the session id that was supplied by the client for the current request is valid.
abstract boolean	isSecure() Return true if the connection for the current request is secure, for example it uses HTTPS.
abstract boolean	isUserInRole(java.lang.String role) Return true if the identity of remote user has been established and the user has been assigned the role.
abstract void	removeAttribute(java.lang.String name) Remove an attribute for the current connection.
abstract void	reset()
abstract void	resetBuffer()
abstract java.lang.String	resolveURL(java.lang.String partialUrl) Resolve a url so that it makes a request to the portal
abstract java.lang.String	resolveURL(java.lang.String partialUrl, boolean isSecure) Resolve a url so that it makes a request to the portal with the specified level of security.
abstract void	sendRedirect(java.lang.String location)
abstract void	setAttribute(java.lang.String name, java.lang.Object o) Set an attribute for the current connection.
abstract void	setBufferSize(int size)
abstract void	setCharacterEncoding(java.lang.String enc)
void	setConnectionFailed() Used to indicate that the connection has failed.
void	setConnectionFailed(java.lang.Exception ex) Used to indicate that the connection has failed.
abstract void	setContentType(java.lang.String contentType) Set the content type to use for the response.
abstract void	setLocale(java.util.Locale locale) Set the locale to use for the response.
abstract void	setProperty(java.lang.String name, java.lang.String value) Set a property to be returned to the client.
abstract void	setSubmitCharacterEncoding(java.lang.String enc) Override the character encoding used by the Reader obtained using #getReader.
void	start(Portal portal, InvocationFactory invocationFactory)

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

PORTLET_CONNECTION

public static final java.lang.String PORTLET_CONNECTION

Name of the request attribute that stores the connection

See Also:

Constant Field Values

log

public static final java.util.logging.Logger log

Constructor Detail

PortletConnection

protected PortletConnection()

Method Detail

getConnection

public static PortletConnection getConnection(PortletRequest portletRequest)

Return the connection that corresponds to the PortletRequest

getPortal

public static Portal getPortal(PortletRequest portletRequest)

Return the Portal that corresponds to the PortletRequest, or null if there is not a current Portal or Connection.

getAction

public static Action getAction(PortletRequest portletRequest)

Return the Action that corresponds to the PortletRequest, or null if there is not a current Action or Connection.

getRender

public static Render getRender(PortletRequest portletRequest)

Return the Render that corresponds to the PortletRequest, or null if there is not a current Render or Connection.

getId

public java.lang.String getId()

A unique identifier for this connection object, used for debugging

start

public void start(Portal portal,
                  InvocationFactory invocationFactory)

finish

public void finish()

getPortal

public Portal getPortal()

setConnectionFailed

public void setConnectionFailed()

Used to indicate that the connection has failed. A connection fails if an unrecoverable error occurs.

setConnectionFailed

public void setConnectionFailed(java.lang.Exception ex)

Used to indicate that the connection has failed. A connection fails if an unrecoverable error occurs.

isConnectionFailed

public boolean isConnectionFailed()

A connection fails if an unrecoverable error occurs.

handleConstraintFailure

public abstract boolean handleConstraintFailure(Constraint constraint,
                                                int failureCode)
                                         throws java.io.IOException

Handle a constraint failure by sending some response to the client.

Returns:

false if the connection cannot handle the constraint failure.

Throws:

java.io.IOException

handleException

public abstract boolean handleException(java.lang.Exception exception)

Handle an exception by sending some response to the client.

Returns:

false if the connection cannot handle the constraint failure.

canGuaranteeIntegrity

public abstract boolean canGuaranteeIntegrity()

Return true if the connection can guarantee integrity (preventing data tampering in the communication process).

canGuaranteeConfidentiality

public abstract boolean canGuaranteeConfidentiality()

Return true if the connection can guarantee confidentiality (preventing reading while in transit).

setAttribute

public abstract void setAttribute(java.lang.String name,
                                  java.lang.Object o)

Set an attribute for the current connection. Attributes are name/value pairs that are valid for the duration of one connection.

getAttribute

public abstract java.lang.Object getAttribute(java.lang.String name)

Get an attribute for the current connection. Attributes are name/value pairs that are valid for the duration of one connection.

removeAttribute

public abstract void removeAttribute(java.lang.String name)

Remove an attribute for the current connection. Attributes are name/value pairs that are valid for the duration of one connection.

getAttributeNames

public abstract java.util.Enumeration getAttributeNames()

Get a list of all attributes for the current connection. Attributes are name/value pairs that are valid for the duration of one connection.

Returns:

an Enumeration of String

getPortletSession

public abstract PortletSession getPortletSession(boolean create)

Return a PortletSession for the current client, or null if one is not available. A PortletSession once established will be consistently returned for a client on subsequent requests. Different clients will never have the same PortletSession.

Parameters:

create, - if true create a new session if one does not already exist for the client.

getScheme

public abstract java.lang.String getScheme()

Return the scheme portion of the url that was used to make the request.

See Also:

javax.portlet.PortletRequest#getScheme

getServerName

public abstract java.lang.String getServerName()

Return the host name portion of the url that was used to make the request.

See Also:

javax.portlet.PortletRequest#getServerName

getServerPort

public abstract int getServerPort()

Return the port portion of the url that was used to make the request.

See Also:

javax.portlet.PortletRequest#getServerPort

getContextPath

public abstract java.lang.String getContextPath()

Return the path to the portal portion of the url that was used to make the request.

See Also:

javax.portlet.PortletRequest#getContextPath

getAuthType

public abstract java.lang.String getAuthType()

Return the authentication scheme used for the current request.

Returns:

PortletRequest.BASIC_AUTH, PortletRequest.CLIENT_CERT_AUTH, PortletRequest.DIGEST_AUTH, PortletRequest.FORM_AUTH, or a custom method.

See Also:

javax.portlet.PortletRequest#getAuthType

isSecure

public abstract boolean isSecure()

Return true if the connection for the current request is secure, for example it uses HTTPS.

See Also:

javax.portlet.PortletRequest#isSecure

getRequestedSessionId

public abstract java.lang.String getRequestedSessionId()

Return the session id that was supplied by the client for the current request.

See Also:

javax.portlet.PortletRequest#getRequestedSessionId

isRequestedSessionIdValid

public abstract boolean isRequestedSessionIdValid()

Return true the session id that was supplied by the client for the current request is valid.

See Also:

javax.portlet.PortletRequest#isRequestedSessionIdValid

getRemoteUser

public abstract java.lang.String getRemoteUser()

Return the identity of the remote user, null if the identity has not been established.

See Also:

javax.portlet.PortletRequest#getRemoteUser

getUserPrincipal

public abstract java.security.Principal getUserPrincipal()

Return a Principal that contains the identity of the remote user, null if the identity has not been established.

See Also:

javax.portlet.PortletRequest#getUserPrincipal

isUserInRole

public abstract boolean isUserInRole(java.lang.String role)

Return true if the identity of remote user has been established and the user has been assigned the role.

See Also:

javax.portlet.PortletRequest#isUserInRole

getProperty

public abstract java.lang.String getProperty(java.lang.String propertyName)

Return the value of the specified connection property as a String, null if the property was not provided by the request from the client. "properties" correspond to HTTP headers in the request for HTTP connections.

See Also:

javax.portlet.PortletRequest#getProperty

getProperties

public abstract java.util.Enumeration getProperties(java.lang.String propertyName)

Return the values of the specified connection property as an array of Strings, null if the property was not provided by the request from the client. "properties" correspond to HTTP headers in the request for HTTP connections.

Returns:

an Enumeration of String

See Also:

javax.portlet.PortletRequest#getProperties

getPropertyNames

public abstract java.util.Enumeration getPropertyNames()

Return the names of available properties for the connection. "properties" correspond to HTTP headers in the request for HTTP connections.

Returns:

an Enumeration of String

See Also:

javax.portlet.PortletRequest#getPropertyNames

getClientContentTypes

public abstract java.util.Set<java.lang.String> getClientContentTypes()

Get the content types acceptable to the client. The returned Set is ordered, the most preferrable content types appear before the least preferred. A return of null or an empty Set indicates that the client content types cannot be determiend, and is treated as an indication that any locale is acceptable.

getClientLocales

public abstract java.util.Set<java.util.Locale> getClientLocales()

Get the locales acceptable to the client. The returned Set is ordered, the most preferrable locale appears before the least preferred. If the client supports all locales, then a Locale("","","") will be present in the returned Set. A return of null or an empty Set indicates that the client locales cannot be determiend, and is treated as an indication that any locale is acceptable.

getClientCharacterEncodings

public abstract java.util.Set<java.lang.String> getClientCharacterEncodings()

Get the character encodings acceptable to the client. The returned Set is order, the most preferrable character encoding appears before the least preferred. A return of null or an empty Set indicates that the client character encodings cannot be determiend, and is treated as an indication that any locale is acceptable.

getSubmitContentType

public abstract java.lang.String getSubmitContentType()

Return the MIME type of the data supplied as the "body" of the request, null if not known.

See Also:

javax.portlet.ActionRequest#getContentType

getSubmitContentLength

public abstract int getSubmitContentLength()

Return the length of of the data supplied as the "body" of the request, -1 if not known.

See Also:

javax.portlet.ActionRequest#getContentLength

getSubmitInputStream

public abstract java.io.InputStream getSubmitInputStream()
                                                  throws java.io.IOException,
                                                         java.lang.IllegalStateException

Return the binary body of the current request.

Throws:

java.lang.IllegalStateException - if getReader() has already been called for this connection.

java.io.IOException

See Also:

javax.portlet.ActionRequest#getPortletInputStream

setSubmitCharacterEncoding

public abstract void setSubmitCharacterEncoding(java.lang.String enc)
                                         throws java.io.UnsupportedEncodingException,
                                                java.lang.IllegalStateException

Override the character encoding used by the Reader obtained using #getReader. This method must be called prior to reading input using #getReader or #getPortletInputStream.

Throws:

java.io.UnsupportedEncodingException

java.lang.IllegalStateException - if getReader() has already been called for this connection.

See Also:

javax.portlet.ActionRequest#setCharacterEncoding

getSubmitCharacterEncoding

public abstract java.lang.String getSubmitCharacterEncoding()

Return the name of the character encoding that will be used by the Reader obtained using #getReader, null if none.

See Also:

javax.portlet.ActionRequest#getCharacterEncoding

getSubmitReader

public abstract java.io.BufferedReader getSubmitReader()
                                                throws java.io.UnsupportedEncodingException,
                                                       java.io.IOException

Throws:

java.io.UnsupportedEncodingException

java.io.IOException

encodeURL

public abstract java.lang.String encodeURL(java.lang.String path)

Encode a url with any special encoding needed by the protocol, for example by adding a sesison id.

resolveURL

public abstract java.lang.String resolveURL(java.lang.String partialUrl)

Resolve a url so that it makes a request to the portal

resolveURL

public abstract java.lang.String resolveURL(java.lang.String partialUrl,
                                            boolean isSecure)
                                     throws PortletSecurityException

Resolve a url so that it makes a request to the portal with the specified level of security.

Throws:

PortletSecurityException

sendRedirect

public abstract void sendRedirect(java.lang.String location)
                           throws java.lang.IllegalStateException,
                                  java.io.IOException

Throws:

java.lang.IllegalStateException

java.io.IOException

setProperty

public abstract void setProperty(java.lang.String name,
                                 java.lang.String value)

Set a property to be returned to the client. "properties" correspond to HTTP headers in the response for HTTP connections.

See Also:

javax.portlet.PortletResponse#setProperty

addProperty

public abstract void addProperty(java.lang.String name,
                                 java.lang.String value)

Add a value to a property to be returned to the client. "properties" correspond to HTTP headers in the response for HTTP connections.

See Also:

javax.portlet.PortletResponse#addProperty

setContentType

public abstract void setContentType(java.lang.String contentType)

Set the content type to use for the response.

getContentType

public abstract java.lang.String getContentType()

Return the content type established with setContentType(), or null if setContentType() has not been called.

setLocale

public abstract void setLocale(java.util.Locale locale)

Set the locale to use for the response.

getLocale

public abstract java.util.Locale getLocale()

Return the Locale established with setLocale(), or null if setLocale() has not been called.

setBufferSize

public abstract void setBufferSize(int size)

getBufferSize

public abstract int getBufferSize()

flushBuffer

public abstract void flushBuffer()
                          throws java.io.IOException

Throws:

java.io.IOException

resetBuffer

public abstract void resetBuffer()

reset

public abstract void reset()

isCommitted

public abstract boolean isCommitted()

getOutputStream

public abstract java.io.OutputStream getOutputStream()
                                              throws java.io.IOException

Throws:

IllegalStatementException - if the content type has not been set with setContentType.

java.io.IOException

getCharacterEncoding

public abstract java.lang.String getCharacterEncoding()

setCharacterEncoding

public abstract void setCharacterEncoding(java.lang.String enc)
                                   throws java.io.UnsupportedEncodingException

Throws:

java.io.UnsupportedEncodingException

getWriter

public abstract java.io.PrintWriter getWriter()
                                       throws java.io.IOException

Throws:

IllegalStatementException - if the content type has not been set with setContentType.

java.io.IOException

getAction

public Action getAction(Window window,
                        java.lang.String namespace)
                 throws PortletException,
                        java.io.IOException

Get an Action for a namespace. Return null if the action stage for the request is complete or there is some other reason that the window and it's children should not proceed further in the action stage.

Throws:

PortletException - if the namespace has already been seen in the actionstagephase of this connection

java.io.IOException

getCurrentAction

public Action getCurrentAction()

Get the current Action object, established from a call to getRender().

getRender

public Render getRender(Window window,
                        java.lang.String namespace)
                 throws PortletException,
                        java.io.IOException

Get a Render for a namespace. Return null if there is some reason that the window and it's children should not be rendered.

Throws:

PortletException - if the namespace has already been seen in the render phase of this connection

java.io.IOException

getCurrentRender

public Render getCurrentRender()

Get the current Render object, established from a call to getRender().

checkForFailure

public void checkForFailure()
                     throws PortletException

Throw an exception if an error was encountered when using this conneciton.

Throws:

PortletException

isPrivate

protected boolean isPrivate()

Used in derived classes during finish() to determine if the response is private

getExpirationCache

protected int getExpirationCache()

Used in derived classes during finish() to determine the maximum expires time for the connection, derived classes use this value to send an expires timeout to the client. -1 means never expire, 0 means expire immediately, otherwise it is a number in seconds.