The getResource operation currently shares both input and output structures with the getMarkup operation, resulting in significant complexity in the descriptive language. This proposal seeks to cleanly separate these.

6.1.12x MimeRequest Type

The MimeRequest structure contains information frequently used to control generation of items with varying mime types.

MimeRequest

[R]

boolean

secureClientCommunication

[R]

string

locales[]

[R]

string

mimeTypes[]

[R]

string

mode

[R]

string

windowState

[O]

ClientData

clientData

[O]

NavigationalContext

navigationalContext

[O]

string

markupCharacterSets[]

[O]

string

validateTag

[O]

string

validNewPortletModes[]

[O]

string

validNewPortletWindowStates[]

[O]

Extension

extensions[]

Members:

* secureClientCommunication: A flag indicating whether or not the Consumer knows the delivery channel between the client and Consumer to be secure [A609] [R401] [R408]. The Consumer MUST set the secureClientCommunication flag as the Portlet MAY render different content when it knows the delivery channel is secure.

* locales: An array of locales where the order in the array is the Consumer's order of preference for the Portlet to generate any returned markup (e.g. "en-US"). Note that current practice on the Internet uses the format [2 char language code][9]"-" [2 char country code][10] as per the provided example. The Consumer can supply this information based on the locale of the page requesting the resource, but is encouraged to also take into account the locales the PortletDescription declared were supported for the mime type being requested.

* mimeTypes: An array of Mime types[11] (e.g. "text/html", "application/xhtml+xml", etc.) where the order in the array is the preferred order (i.e. first is most preferred, second is next preferred, etc.). In addition to fully specified Mime types, use of "*" (indicates all Mime types are acceptable) and type/* (where type includes things such as "text") from the HTTP definition[12] MAY be specified. The response SHOULD use one of the specified Mime types. The Producer/Portlet does not have to process any optional parameters that can be included on mime type declarations. If the Consumer has no knowledge of the appropriate mime type, a value of "*" can be supplied to the Portlet.

* mode: The current mode for the Portlet.

* windowState: The current window state for the Portlet.

* clientData: A structure that provides information about the client device which will render the response.

* navigationalContext: The Portlet's current NavigationalContext

* markupCharacterSets: An array of characterSets[13] (e.g. "UTF-8", "ISO-10646-Unicode-Latin1", etc.) the Consumer is willing to have the Portlet use for encoding any returned markup (i.e. the character set for the aggregated page). The order of this array indicates the preferred ordering of the Consumer with the first element in the array being the most preferred. When the SOAP binding is in use, the Producer MUST either use one of the markupCharacterSets, UTF-8 or UTF-16 for the response message as the nature of XML requires the character set used for the markup to be the same as the response message.

* validateTag: This field MAY contain a validateTag previously supplied to the Consumer in a CacheControl structure. When this field has a value, the Consumer is indicating it has cached a previous response of this resource for the Portlet, but the CacheControl structure governing the use of that cached resource no longer indicates it is valid. The Consumer is supplying the validateTag as a means for the Portlet to avoid generating the resource if the cached resource can be validated. The Portlet sets the useCachedResource field in the returned ResourceResponse to "true" to indicate the resource referenced by the validateTag is still valid.

* validNewPortletModes: Current set of modes the Producer MAY request changing to. These can be used to specify a mode change on a URL written into the response. It should be noted that this is no guarantee that a requested transition will be honored, as factors not easily represented may cause the Consumer to reject a requested transition. The primary reason for supplying this information is to assist the Portlet in preparing a user interface that does not contain links the Consumer will not honor. If no values are supplied, the Portlet can assume that all transitions are valid. Consumers can indicate they prohibit all transitions by supplying just the current mode in this array.

* validNewPortletWindowStates: An array of windowStates which the Consumer is indicating as available to be requested as a newWindowState on a URL embedded in the response. It should be noted that this is no guarantee that a requested transition will be honored, as factors not easily represented may cause the Consumer to reject a requested transition. The primary reason for supplying this information is to assist the Portlet in preparing a user interface that does not contain links the Consumer will not honor. If no values are supplied, the Portlet can assume that all transitions are valid. Consumers can indicate they prohibit all transitions by supplying just the current windowState in this array.

* extensions: The extensions field MAY be used to extend this structure. Extension elements MUST be from namespaces other than WSRP.

6.1.13 MarkupParams Type

The schema definition of the MarkupParams structure extends the common MimeRequest definition (see Section 6.1.12x) without any additional fields and provides the data needed for the Portlet to generate markup that will enable the End-User to visualize the state of the Portlet. These are also supplied to the interaction processing operations as they may impact that processing (e.g. validNewModes) and those operations are allowed to return markup and thereby avoid an additional invocation.

[Delete the "code" block and field descriptions as everything happens via the extends statement.]

6.1.13x ResourceParams Type

The schema definition of the ResourceParams structure extends the common MimeRequest definition (see Section 6.12x), adding the following fields specific to invoking the getResource operation.

ResourceParams (also see the fields defined in Section 6.12x)

[R]

ID

resourceID

[O]

string

resourceState

[O]

NamedString

formParameters[]

[O]

UploadContext

uploadContexts[]

Members:

* resourceID: This field provides the identifier the Portlet had placed on the URL requesting the resource.

* resourceState: The state encoded on the resource URL using the wsrp-resourceState portlet URL parameter.

* formParameters: Name/value pairs reflected, for example, in the case of HTML either from the query string of forms submitted with method=GET or in a request with mime type = "application/x-www-form-urlencoded" submitted with method=POST. For the case of query string parameters, Consumers should take care with regard to how user-agents encode this data. In particular, common user-agents (i.e. web browsers) encode posted data in the character set of the response that generated the page the form is on. As the Producer is ignorant of this encoding and the Consumer is required to consistently encode parameters passed to the Producer in the SOAP message, Consumers MUST ensure that form data is properly decoded before it is passed to the Producer.

* uploadContexts: An optional field where mime types not parsed into formParameters are placed for transfer to the Producer.

6.1.xx 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]

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 useCachedMarkup 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 markup is returned, and if the markupBinary field is used to return such markup, 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 returned item MUST either match that requested by the Consumer, be UTF-8 or UTF-16. When a SOAP binding is used, the XML specification requires the item's character set match the character set of the response message's document. This field is only missing when the useCachedItem flag is "true" or the itemBinary field has a value. This field is mutually exclusive with returning 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 a value in the itemString field.

* locale: The locale, in 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 returned 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.

* extensions: The extensions field MAY be used to extend this structure. Extension elements MUST be from namespaces other than WSRP.

6.1.xx ResourceContext Type

The schema definition of the ResourceContext structure extends the common MimeResponse definition (see Section 6.1.xx) without any additional fields.

6.1.xx ResourceResponse Type

The ResourceResponse structure contains fields for returning various items in response to a getResource invocation.

ResourceResponse

[R]

ResourceContext

resourceContext

[O]

SessionContext

sessionContext

[O]

Extension

extensions[]

Members:

* resourceContext: A structure carrying the returned resource and fields related to it.

* sessionContext: This structure contains session-oriented fields that may be returned from various operations, including a new sessionID and the duration before it expires.

* extensions: The extensions field MAY be used to extend this structure. Extension elements MUST be from namespaces other than WSRP.

6.1.14 MarkupContext Type

The schema definition of the MarkupContext structure extends the MimeResponse definition (see Section 6.1.xx), adding fields relative to returning a Portlet's markup.

MarkupContext (also see the fields in 6.1.xx)

[O]

string

preferredTitle

Members:

* preferredTitle: The title the Portlet would prefer to be used in any decoration of the markup. The locale and markup type, for textual markup types only, of the preferred title has to be identical to that of the markup.

10.2.1.1.3.4 wsrp-resourceState

The value of this portlet URL parameter defines the state which the Consumer MUST send in the resourceState field of the ResourceParams structure when the URL is activated. If this parameter is missing, the Consumer MUST NOT supply a value in the resourceState field of the ResourceParams structure.

10.2.3 BNF Description of URL formats (merge with other updates to this section)

ResourceTextName = "wsrp-url"

"wsrp-resourceID"

"wsrp-resourceState"

Miscellaneous changes

  1. The signatures in 6.3 and 4.2 would change to:

 ResourceResponse = getResource  (registrationContext, portletContext, runtimeContext, userContext, resourceParams );
  1. Appendix E will need updating to reflect the new structures and changes in the subsection numbering.
  2. 6.3.1: change
    "This operation is used whenever the activated URL has specified a value of true 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. This operation reuses the MarkupResponse structure since any mime type could be returned. Consumers SHOULD supply a value of "*" in the mimeTypes field of the MarkupParams structure as the returned object is likely to just be streamed to the End-User."
    to
    "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 portlet URL parameter (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."

  3. 10.2.2.5: Drop references to wsrp-navigationalValues and wsrp-navigationalState and add a reference to wsrp-resourceState

  4. 10.2.2.7: Add references to resource oriented URLs and wsrp-resourceID and wsrp-resourceState

Issues/Resolution

[Subbu] The names MimeRequest and MimeResponse seem unintuitive, since we're not really talking of multipart requests or responses. I'm unable to come up with a better term right now, but I would suggest we look for a better one.

[Subbu] The mimeTypes field should reflect the current order in the schema - i.e. it should be just after locales.

[Subbu] In 6.1.13, we don't need to rename the element name markupParams to mimeRequest.

[Subbu] Why exclude preferredTitle from the response type? It is optional anyway. The plus side of keeping it in the response structure is that we can avoid changing MarkupContext.

[Subbu] In 6.1.14, we don't need to change the element name markupContext to markupItem. Also noted that, under member description, the proposal uses resourceItem instead of markupItem.

Resource-specific_structures (last edited 2009-08-12 18:06:25 by localhost)