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 <>
02/08/2007 05:48 PM
To
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 "<"), 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.
