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 Title: Client Attributes
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.