Re: [wsrp-interfaces] Client Attributes

[Rich Thompson <richt2@us.ibm.com>]

1. I do think the requirements introduced
in 6.1.10 & 6.1.16 will be untestable. As I went to write it, I also
realized that a MUST statement would likely place an unintended requirement
on the HTTP proxy case; namely, passing the additional data which the in-protocol
method supplies.

2. While the Consumer is required to
support both means of getting a resource, that doesn't mean that both will
be supported by the Producer for any given resource.

Rich

Michael Freedman <michael.freedman@oracle.com>

02/08/2007 05:48 PM

To	wsrp-interfaces@lists.oasis-open.org
cc
Subject	Re: [wsrp-interfaces] 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

---

Next change 
6.1.10 ClientData Type
The ClientData structure contains information
the client supplied to Consumer about itself, including user-agent identification
and capabilities.

ClientData
[O] string	userAgent
[O] CCPPHeaders	ccppHeaders
[O] string	requestVerb
[O] NamedString	clientAttributes[]
[O] Extension	extensions[]

Members:

• 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.

MimeResponse
[O] boolean	useCachedItem
[O] string	mimeType
[O] string	itemString
[O] base64Binary	itemBinary
[O] string	locale
[O] boolean	requiresRewriting
[O] CacheControl	cacheControl
[O] string	ccppProfileWarning
[O] NamedString	clientAttributes[]
[O] Extension	extensions[]

Members:

• 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 "&lt;"), 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.

6.3 getResource Operation
The Consumer requests a resource by invoking:

ResourceResponse = getResource (registrationContext, portletContext, runtimeContext, userContext, resourceParams );
Faults:	AccessDenied, InconsistentParameters, InvalidCookie, InvalidHandle, InvalidRegistration, InvalidSession, InvalidUserCategory, MissingParameters, ModifyRegistrationRequired, OperationFailed, ResourceSuspended, UnsupportedLocale, UnsupportedMimeType, UnsupportedMode, UnsupportedWindowState

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.