Resource objects counter proposal From Paul Moore and Tom Hastings 11/27/00 File: resource-objects-counter-proposal-001127-rev.doc This document is a counter proposal to the one that Ira McDonald and Tom Hastings prepared for the September 2000 PWG meeting that defined a general Resource object with a "resource-type" attribute for sub-typing and operations to query, create, and delete Resource object instances. See ftp://ftp.pwg.org/pub/pwg/ipp/new_RES/draft-ietf-ipp-get-resource- 01.pdf Table of Contents 1 Introduction and Summary...........................................1 2 Get-Printer-Collection-Rows operation..............................2 3 Operations to Add, Delete, or Modify Collection rows...............3 3.1 Add-Printer-Collection-Row.....................................4 3.2 Delete-Printer-Collection-Row..................................4 3.3 Modify-Printer-Collection-Row operation........................4 4 Get-Printer-Collection-Row-Data, Set-Printer-Collection-Row-Data operations.............................................................5 5 Observations.......................................................5 6 Suggested member attributes........................................6 7 Possible '1setOf collection' Printer attributes....................7 8 Examples...........................................................7 8.1 Input-trays....................................................7 8.2 Media descriptions.............................................7 8.3 Images.........................................................8 1 Introduction and Summary Use '1setOf collection' attributes to describe fonts, media, paper trays, downloaded JPEGs, ICC Color Profiles, macros, . Some of these resources can be down-loaded into the Printer, some can be installed by means outside the IPP protocol, and some can be properties or characteristics of the Printer as it comes from the vendor or is configured by the administrator when the Printer is installed. Some of these resources can have associated opaque binary data, such as font data, while others consist solely of attributes. These collection attributes are retrieved using the regular GetPrinterAttributes operation, since they are ordinary collection attribute with an attribute syntax of '1setOf collection'. More than one can be asked for in a request. All of the members of all of the rows are returned (as per the current collections spec). Note: according to the 1 collection spec the "xxx-supported" Job Template attributes usually have the attribute syntax: '1setOf type2 keyword', rather than '1setOf collection'. The keywords indicate which member attributes are supported for the collection and the corresponding "xxx-supported" indicate the values supported for each "xxx" member attribute. For such Job Template attributes, a new naming convention is introduced: "xxx- rows" for the Printer attributes with the attribute syntax of '1setOf collection'. The "xxx-rows" (1setOf collection) attributes are never returned by Get- Printer-Attributes unless they are explicitly asked for (i.e., they are never included in groups or 'all', since there would be too much data in the response). A single row can be queried using a new Get-Printer- Collection operation described in the next section. The following new operations are defined for use with '1setOf collection' attributes: - Get-Printer-Collection-Rows - return rows of a '1setOf collection Printer attribute based on a simple filter supplied by the client - Add-Printer-Collection-Row - add a row to a '1setOf collection' Printer attribute - Delete-Printer-Collection-Row - delete a row of a '1setOf collection' Printer attribute - Modify-Printer-Collection-Row - modify a row of a '1setOf collection' Printer attribute - Get-Printer-Collection-Row-Data - same as Get-Printer-Collection- Row, and in addition get the row's associated opaque data. - Set-Printer-Collection-Row-Data - same as Set-Printer-Collection- Row, and in addition set the row's associated opaque data. For consistency all six operations have an Operation Attributes Group and a Printer Attributes Group in each request and response. The response always includes all of the member attributes of each row returned. In addition to the usual request operation attributes for a Printer operation, all six operations MUST include: "collection-attribute" (type2 keyword) - which identifies the collection attribute to be affected. For example: "collection-attribute" = 'font-rows-supported' or "collection- attribute" = 'tray-rows-supported' 2 Get-Printer-Collection-Rows operation The Get-Printer-Collection-Rows operation retrieves one or more values of a 1setOf collection attribute. Each collection value is called a "row". The rows are selected on the basic of a filter specified in the operation. Only one Filter Attribute is permitted and it is expressed as the only attribute in the Printer Attributes group. The Printer matches the Filter Attribute against all the member attribute of all of the rows in the collection value. The attribute name, syntax, and value of the Filter Attribute MUST be the same as the member attribute in the 1setOf collection, in order to match. A value match occurs if all of the 2 values of the Filter Attribute are a subset of the member attribute of a row.. The client MUST also supply the Filter Attribute as the only attribute in a separate Printer Attributes group. For example: "font-point-size" = '12' The Printer returns all member attributes of all rows of the collection that match the Filter Attribute. Each row is returned in a separate Printer Attributes group in the response (like Get-Jobs response). If no rows match then the status code 'client-error-not-found' error is returned. ISSUE: Or should the status code be 'successful-ok' (0), with an empty Printer Attributes group returned to be more like Get- Printer-Attributes? When a collection attribute with a 1setOf collection attribute syntax is defined, the definition SHOULD specify an 'identifying member attribute', called the Key Attribute that uniquely identifies a row. No two rows can have the same Key Attribute value. The role of the Key Attribute is the same as a primary key in a data base. The Key Attribute facilitates direct indexing into 1setOf collection attributes. Possible examples could be tray name, media name, font name, etc. In some cases the identifying member attribute could be a printer generated unique ID. If a collection attribute has a '1setOf collection' attribute syntax, but the definition of that attribute does not indicate which member attribute is the Key Attribute, that collection attribute MAY still be used in the Get-Printer-Collection-Rows operation, but there is no way for the client to unambiguously request a single row. 3 Operations to Add, Delete, or Modify Collection rows The operations defined in this section add, delete, or modify a row in a '1setOf collection' Printer attribute that is defined to have a Key Attribute. These operation do not work on all collections - there are some collections that represent state or non-logical capabilities of the device (paper loaded, input trays, etc.). In this case the collections are read-only (either by definition or in a particular implementation). There also can exist Printer collection attributes that represent collections that are software modifiable entities but that are still not updated via these operations in an implementation. For example fonts could be loaded by a specific set of font management operations, rather than these operations. What this means is that the collection querying can be used on all entities that are represented as '1setOf collection' but there can be many mechanisms that create those collections. The definition of the collection MUST indicate how the rows are created, modified, and removed. 3 3.1 Add-Printer-Collection-Row This operation adds a collection row to an existing '1setOf collection' Printer attribute provided that the collection definition defined a Key Attribute. In addition to the "collection-attribute" operation attribute, the client MUST supply the Key Attribute as the first attribute in the Printer Attributes group in the request. For example, "font-name" = 'TimesRomanItalic'. The client supplies the remaining attributes for the row as the remaining attributes in the Printer Attributes group. For example, "font-size" = '12', "font-style" = 'italic', etc. If the row already exists, the Printer MUST reject the request and return the (new) 'client-error-row-already-exists'. If the "collection-attribute" does not specify a '1setOf collection' attribute whose definition includes a Key Attribute or the first attribute in the Printer Attributes group is not the Key Attribute defined for the collection, the Printer MUST reject the request with the 'client-error-bad-request'. 3.2 Delete-Printer-Collection-Row This operation deletes a collection row from an existing '1setOf collection' Printer attribute provided that the collection definition defined a Key Attribute. In addition to the "collection-attribute" operation attribute, the client MUST supply the Key Attribute as the only attribute in the Printer Attributes group in the request. For example, "font-name" = 'TimesRoman'. If the row does not exist, the Printer MUST reject the request and return the 'client-error-not-found' error status code. If the "collection-attribute" does not specify a '1setOf collection' attribute whose definition includes a Key Attribute or the only attribute in the Printer Attributes groups is not the Key Attribute defined for the collection, the Printer MUST reject the request with the 'client-error-bad-request'. 3.3 Modify-Printer-Collection-Row operation This attribute modifies an existing collection row of an '1setOf collection' Printer attribute provided that the collection definition defined a Key Attribute. In addition to the "collection-attribute" operation attribute, the client MUST supply the Key Attribute as the first attribute in the Printer Attributes group in the request. For example, "font-name" = 'TimesRomanItalic'. The client supplies the remaining attributes to be modified for the row as the remaining attributes in the Printer Attributes group. For example, "font-size" = '12', "font-style" = 'italic', etc. Any member attributes of the row that the client omits are unchanged. If the row does not exist, the Printer MUST reject the request and return the 'client-error-not-found' error status code. 4 If the "collection-attribute" does not specify a '1setOf collection' attribute whose definition includes a Key Attribute or the first attribute in the Printer Attributes groups is not the Key Attribute defined for the collection, the Printer MUST reject the request with the 'client-error-bad-request'. 4 Get-Printer-Collection-Row-Data, Set-Printer-Collection-Row-Data operations Some '1setOf collection' attributes may have data associated with their rows. In this case then one choice available to the designer of the collection is to use the Get-Printer-Collection-Row-Data and Set- Printer-Collection-Row-Data operations to read and write opaque blobs. For the Get-Printer--Collection-Row-Data, the client supplies the "collection-attribute" name and the Key Attribute as in the other Collection Row operations. The row's attributes are returned in the Printer Attributes Group, followed by the dataas a data stream in the response (packaged the same way the print-job's data is following the 'end-of-attributes-tag'). The data is sent in the same way using the Set-Printer-Collection-Row- Data operation. Note that for some collection it might be possible to read the data but not write it (uploading font metrics from ROM for example). Also it might be possible to write it but not read it (macros are not intended to be used outside the printer so there is not point in providing read capabilities). Alternative design #1. There is a member attribute for each row that specifies a URI for the data. The Add-Printer-Collection-Row operation returns the URI generated by the Printer when the row is created. The data is got and set by HTTP GET and POST to that URI. One problem with using HTTP GET and PUT to get or set data is the security checking. For example, ordinary users may not be able to add some resources to the Printer, such as media, but may be able to add other resources, such as images, to the Printer (for a leased amount of time). Alternative design #2. Collections that have associated data have explicit row creation and operations (Load-Font operation for example) but the data is read by HTTP get or an IPP Get-Printer-Collection-Row- Data. This alternative overcomes the non-atomic nature of adding a row then uploading the data. 5 Observations Some collections may have read-only rows and read-write rows (fonts supported may include ROM fonts and soft fonts). Jobs and Subscriptions could have been done using '1setOf collection' Printer attributes, but since we already have operations defined for Jobs and Subscription objects. Driver down loading could have been done using '1setOf collection' Printer attributes, but we have a specification that uses Get-Printer- Attributes and a new Get-Client-Print-Support-Files operation. 5 Expiration times for collection rows can be specified in the collection definition if that is what the collection needs. For example, if users are allowed to down load images into the Printer for a period of time. This mechanism is only defining a standardized ways of viewing structured data - it does not imply that common mechanisms must be used by implementations. 6 Suggested member attributes In order to get some consistency in definition of '1setOf collection' Printer attributes, the following member attribute names and attribute syntaxes are suggested if the member attribute is appropriate for the resource. However, none of these attributes are REQUIRED for a definition. For key attributes that a client can supply (but cannot modify): xxx-name (name(127)) or xxx-key (name(127) | type3 keyword) - Key Attribute For attributes that a client can supply (or modify): xxx-info (text(127)) - general information xxx-create-date-time (dateTime) - the date and time that the resource was originally created, not added to the Printer. xxx-lease-duration (integer(0:MAX)) - lease duration in seconds, 0 is infinite xxx-data-uri (1setOf uri) - uri of the data when supplied by the client xxx-data-k-octets (integer(0:MAX)) - size of the data xxx-data-compression (type3 keyword) - data compression For READ-ONLY attributes populated by the Printer: xxx-id (integer(1:MAX)) - integer id for those resources that do not have a natural name supplied by the client. xxx-create-user-name (name(MAX)) - user name who added the resource to the Printer xxx-create-time (integer(MIN:MAX)) - the "printer-up-time" when the resource was added to the Printer. A 0 or negative value means before this Printer power-up (see RFC 2911 section 4.3.14). xxx-expiration-time (integer(0:MAX)) - the "printer-up-time" when the lease expires xxx-data-uri (1setOf uri) - uri of the data when supplied by the Printer 6 7 Possible '1setOf collection' Printer attributes Collection Identifying Members Data member Input trays name Loaded media, none state, capacity, level Output bins name State, capacity, none level Fonts Name (face- Size, style, Font metrics supported size-style) format Media- name Size, weight, none descriptions Macros name Date, format Macro data Images name Date, format, Image data description 8 Examples These are examples of how this proposal could be used to represent various items. The full variety of choices is used. These are not intended as actual proposals for their respective collections, but rather just indicate how the mechanism proposed in this paper would work. 8.1 Input-trays The "input-tray-rows-supported" (1setOf collection) Printer attribute contains one row for each input tray supported by the printer. The rows are identified by an "input-tray-name" (type3 keyword | name(MAX)) Key Attribute whose value is either defined by the PWG or is defined by the implementation. The values of the "input-tray-name" member attribute may be submitted in a Job Creation operation as the value of a (new) "input-tray" Job Template attribute. The member attributes include "input-tray-max-capacity", "input-tray- current-level", "input-tray-status", and "input-tray-media-name" with semantics taken from the Printer MIB. The rows of this collection are read using the Get-Printer-Collection- Rows operation. Rows are not created or deleted, though in some implementations, certain member attributes, such as "input-tray-media- name" can be set. 8.2 Media descriptions The "media-rows-supported" (1setOf collection) Printer attribute contains one row for each supported / known media. See the PWG 7 Production Printing Extension spec for the definition of the member attributes. The "media-col" (collection) Job Template attribute can be supplied by the client in Job Creation operations. The rows are identified by a "media-key" (type3 keyword | name(MAX)) Key Attribute whose value is either defined by the PWG or is defined by the administrator. The values of the "media-key" member attribute may be submitted in a Job Creation operation as the value of the IPP/1.1 "media" Job Template attribute. The member attributes include "media-size" (1setOf collection) {x- dimension, y-dimension", "media-weight", "media-color", etc. The rows of this collection are read using Get-Printer-Collection-Rows. Rows are created using the Add-Printer-Collection-Row operation and deleted using the Delete-Printer-Collection-Row operation. 8.3 Images The "image-rows-supported" (1setOf collection) Printer attribute contains one row for each supported / known. The rows are identified by an "image-name" (name(MAX)) Key Attribute whose value is either defined by its creator. The values of the "image- name" member attribute may be submitted in a Job Creation operation as the value of the (new) "image" Job Template attribute. Member attributes include "image-size", "image-format", "image-version", etc. The images are created by a (new) image-specific operation: Load- Image. This operation includes all the member attributes that describe the image plus the image data as an attached 'print-job' data stream. Some member attributes are derived from the image (size for example). The Set-Printer-Collection-Row-Data operation is not used. Instead, a (new) Load-Image operation is defined and the client may specify an expiration time for the image. Images may be explicitly deleted using the Delete-Printer-Collection-Row operation. The Add-Printer-Collection-Row and Modify-Printer-Collection- Row operations are not defined for use with images. The image data is not readable externally. 8