From: Michael Freedman <michael.freedman@oracle.com>
To: wsrp-interfaces@lists.oasis-open.org
Date: Thu, 08 Feb 2007 14:48:50 -0800
Title: Client Attributes
Thnaks. This looks great! Two questions:
1) You choose SHOULD over MUST -- is this because you don't think its
testable? Why does the consumer need the flexibility to have the
in-protocol request/response behave differently then the out of band
one>
2) In section 6.3 the inserted sentence has "when both are supported".
but then 10.2.1.1.3 says that a consumer must support both. So why
this extra language?
Rich Thompson wrote:
Here is the write-up requested as a
result of today's discussion of the points Mike raised on an email
thread.
It should also be noted that this applies to public review comments #8
& #21.
Rich
6.1.10 ClientData Type
The ClientData
structure contains information the client supplied to Consumer about
itself, including user-agent identification and capabilities.
userAgent: String identifying
the user-agent of the End-User.
ccppHeaders:
Contains the WSRP representation of the CCPP Headers which were
received or produced by the Consumer.
requestVerb: This
field provides the means for the Producer to be notified of the
transport level verb (e.g. in HTTP these are: "GET", "POST", "PUT" and
"DELETE") used for the End-User interaction. The primary purpose of
this field is to allow the Producer to communicate with other systems
with the same semantics as the End-User interaction.
clientAttributes:
Attributes received from the client (e.g. HTTP headers) which are not
represented elsewhere within the WSRP protocol and which the Consumer
is choosing to supply to the Portlet. When this structure is being
supplied to the getResource operation, Consumers SHOULD supply
the same set of items which would have been supplied using the HTTP
proxy method of serving the resource.
extensions: The extensions field MAY be used to extend this
structure. Extension elements MUST be from namespaces other than WSRP.
6.1.16 MimeResponse
Type
The MimeResponse
structure contains common fields relative to returning an item
described by a mime type.
useCachedItem: A
boolean used to indicate whether the item the Consumer indicated it has
cached is still valid. The default value of this field is "false" (i.e.
a new item is being returned for the Consumer's use). If the value for useCachedItem is "true"
the itemString and itemBinary fields MUST NOT be returned. If the
field's value is "true", any supplied cacheControl field MUST be processed as a
replacement for the cacheControl
originally supplied with the cached item.
mimeType: The mime
type of the returned item. The mimeType
field MUST be specified whenever an item is returned, and if the itemBinary field is used to return the item,
the mime type MUST include the character set for textual mime types
using the syntax specified in RFC1522[14] (e.g. "text/html; charset=UTF-8"). In
this particular case this character set MAY be different than the
response message.
itemString: This is
a string version of the item. If this is encoded in a SOAP message
(i.e. XML), various characters will likely need to be escaped using XML
entities (e.g. "<" becomes "<"), either by the Portlet or the
Producer's runtime. The character set of the markup a Portlet returns
MUST either match that requested in MimeRequest,
be UTF-8 or UTF-16. When a SOAP binding is used, the XML specification
requires the character set of the markup match the character set of the
response message's document. This field is only missing when the useCachedItem flag is "true".
This field is mutually exclusive with returning the markup in the itemBinary field.
itemBinary: The item
represented as a binary stream. This is useful if the item is not
easily mapped to the string type or an attachment scheme is in use that
moves binary types into separate message parts (e.g. DIME). This field
is mutually exclusive with returning the item in the itemString field.
locale: The locale,
if any, for the returned item.
requiresRewriting: A
flag by which the Portlet/Producer indicates whether or not
Consumer-side rewriting (see [Sections 10.2.1] and [Section 10.3.1])
is required. The Consumer MUST parse the item for rewriting if the
value of requiresRewriting is "true". The default value for this flag is "false".
cacheControl:
Defines the caching policies for the returned item. If the cacheControl field is not supplied, the Portlet is indicating it does not consider the item
cacheable. This is without prejudice to Consumer specific caching
policies.
ccppProfileWarning:
This field can carry a list of warning values as defined in the CC/PP
standard.
clientAttributes:
Attributes which the Portlet wishes to set on the response to the
Consumer's client. Consumer policy will control which of these
attributes are actually set on the response to the client. When this
field is supplied on the response from a getResource operation,
Consumers SHOULD apply the same policy which would have been used for
the HTTP proxy method of serving the resource.
extensions: The extensions field MAY be used to extend this
structure. Extension elements MUST be from namespaces other than WSRP.
This operation's semantics are
that the client/client-agent has requested additional information in a
manner that utilized the Consumer as a proxy for supplying that
information. As the Consumer is only being used as a
proxy for accessing the resource, a number of techniques for storing
the Portlet's navigationalContext are
not available to it. As a result, while the Portlet's navigationalContext is supplied to this
operation, neither the URL nor the response are permitted to change
this navigationalContext. If a logical
side effect of the invocation is changing the Portlet's navigationalContext, either the Portlet or the
Producer will need to manage this change until the next opportunity to
return the navigationalContext to the
Consumer.
This operation can be used to
fetch a resource whenever the activated URL has specified a value for
the wsrp-resourceID portlet URL
parameter and is the preferred mechanism whenever a value of true is specified for the wsrp-preferOperation (see [Section 10.2.1.1.3.3]. It provides
all the contextual information needed for a Portlet to re-establish its
state relevant to the End-User so that the generated response is able
to take that state into account. The result of
this operation SHOULD be identical to that achieved using the HTTP
proxy method when both are supported.
Resources which are inserted
into the Consmer's aggregated page MUST follow the guidelines in [Section 10.4] for the mime types
described there and the relevant fragment rules, if any, for other mime
types.
10.2.1.1.3 wsrp-urlType = resource
Activation of the URL will result in the Consumer
acting as a gateway to the underlying resource, possibly in a cached
manner, and returning it to the user-agent. The URL for the resource
(including any query string parameters) is encoded as the value of the wsrp-url parameter. When a portlet URL
specifies "resource" for the wsrp-urlType
portlet URL parameter, either the wsrp-resourceID portlet URL parameter or a
combination of the wsrp-requiresRewrite
and the wsrp-url portlet URL parameters
MUST also be specified. Since the Portlet is allowed
to specify either both or just one of the means of getting a resource,
Consumers will need to support both the transport proxy and SOAP
operation mechanisms in a manner which applies
the same policy regarding the proxying of information between the
client communications and Producer communications. This
flexibility allows the Portlet's markup to control which resource
serving mechanism is in use whenever it needs to and allows for the
Portlet to provide additional guidance when both mechanisms are
supported, since the fidelity of what is presented to the End-User
might depend on which mechanism is selected by the Consumer.