IPP Notification Model From: Tom Hastings Date: 8/02/99 File: ipp-notification-model-990802.doc There are 4 issues highlighted like this that need to be resolved. This paper uses object modeling techniques to describe the current IPP Notification Specification object model (July 22, 1999): ftp://ftp.pwg.org/pub/pwg/ipp/new_NOT/ipp-notification-990722.pdf and the proposed new object model that introduces the Subscription object as an OPTIONAL object when implementing notification. In other words, notification can be implemented with or without the Subscription object. Review of this object model before writing the complete spec will help speed up the production of the spec and will also help with the understanding of the semantics. I suggest that this modeling be kept in the final spec in some form similar to this paper. NOTE - In this model document, the notation [ ] indicates that the sender (client in a request, IPP object in a response, notification sender in a notification) MAY omit the attribute inside the square brackets. For simplicity, the conformance requirements for attribute support are not indicated in this document. 1 Current IPP Notification Operations The current IPP Notification object model (July 22, 1999) consists of the Printer object and the Job object. The following operations are defined for each of the object targets: 1.1 Printer object - current Printer object target: salient inputs beside printer- uri: job creation operations recipients, [events,] [user- data] Subscribe-Printer recipients, [events,] [lease time] Get-Printer-Attributes [requested-attributes] Renew-Printer-Subscription [lease time] Get-Printer-Subscriptions [my-subscriptions] Unsubscribe-Printer subscription-id 1.2 Job object Job object target: salient inputs besides job-id: Subscribe-Job recipients, [events] Get-Job-Attributes [requested-attributes] Unsubscribe-Job subscription-id 1 2 New IPP Notification Operations The Printer, Job, and (new) Subscription object targets have the following operations defined for use with notification: 2.1 Printer object Printer object target: salient inputs beside printer-uri: job creation operations recipients, [events,] [user-data,] [subscription-ids] Get-Printer-Attributes [requested-attributes] Get-Printer-Subscriptions[my-subscriptions] 2.2 Job object Job object target: salient inputs besides job-id/job- uri Get-Job-Attributes [requested-attributes] 2.3 Subscription object - new OPTIONAL package Subscription object related: salient inputs besides printer-uri: Create-Subscription recipients, [events,] [user-data,] [lease-time,] [job-id or printer- uri] Get-Subscription-Attributes subscription-id, [requested- attributes] Renew-Subscription subscription-id, [lease time] Cancel-Subscription subscription-id 3 Notification attributes defined for each object The following notification attributes are defined for each of the Printer, Job, and (new) Subscription objects. Attributes and objects not in the current, July 22, spec are labeled as "new": 2 3.1.1Printer object notification attributes Printer object attributes: set by: printer-trigger-event (type2 keyword) System - event occurring printer-trigger-message (text(255)) System - event occurring printer-trigger-time (integer(MIN:MAX)) System - event occurring printer-trigger-date-time (dateTime) System - event occurring previous-printer-state (type1 enum) System - event occurring printer-state-reasons-added (1setOf type2 keyword) System - event occurring printer-state-reasons-deleted (1setOf type2 keyword) System - event occurring notify-recipients-schemes-supported (1setOf uriScheme) Administrator notify-events-default (1setOf type2 keyword) Administrator notify-events-supported (1setOf type2 keyword) Administrator notify-lease-time-supported (rangeOfInteger(0:MAX)) Administrator notify-lease-time-default (integer(0:MAX)) Administrator max-number-of-subscriptions-supported (integer(1:MAX)) Administrator 3.1.2Job object notification attributes Job object attributes: set by: notify-recipients (1setOf uri) job creation operation notify-events (1setOf type2 keyword) job creation operation notify-user-data (octetString(255)) job creation operation new: job-subscription-ids (1setOf integer(0:MAX)) job creation operation and/or subsequent Create- Subscription 0 indicates no Subscription objects job-trigger-event (type2 keyword) System - event occurring job-trigger-message (text(255)) System - event occurring job-trigger-time (integer(MIN:MAX)) System - event occurring job-trigger-date-time (dateTime) System - event occurring previous-job-state (type1 enum) System - event occurring job-state-reasons-added (1setOf type2 keyword) System - event occurring job-state-reasons-deleted (1setOf type2 keyword) System - event occurring 3 3.1.3Subscription object attributes (new) Subscription object attributes: set by: notify-recipients (1setOf uri) client - Create- Subscription notify-events (1setOf type2 keyword) client - Create- Subscription notify-user-data (octetString(255)) client - Create- Subscription notify-lease-time (integer(0:MAX)) client - Create- Subscription notify-lease-time-remaining (integer(0:MAX)) system - Create- Subscription 0 means infinite (for jobs only) most-recent-sequence-number (integer(0:MAX)) system - event occurring delivery-failure-count (integer(0:MAX)) system - event occurring Note: The "notify-least-time" attribute is the number of seconds granted for the subscription. It is used to restore the subscription on the Restart-Job and Reprocess-Job operations. The "notify-lease-time-remaining" attribute is the number of seconds remaining in the lease. Internally, the implementation may have a more absolute representation of when the least expires, but this relative value is returned to help the client know how much more time is remaining in the lease. A value of 0 is used for Subscriptions associated with Jobs, since they don't have a lease, but depend on the life time of the documents of the Job. The "most-recent-sequence-number" attribute maintains the sequence number that was delivered in the most recent notification for the subscription. The "delivery-failure-count" attribute is the number of transport delivery failures in delivering a notification to any of the "notify- recipients" using the transport indicated. Notification Recipients do not respond to the Notification Source. 4 4 Notification Content The notification content is the same for the current and new specs: 4.1 Basic Job Event Notification content version-number status-code (with the value: basic-job-event(600)) request-id (used as notification delivery sequence number) job-printer-uri (uri) job-id (integer(1:MAX)) job-trigger-event (type2 keyword) [job-trigger-message* (text(255))] job-trigger-time (integer(1:MAX)) [job-trigger-date-time (dateTime)] job-state (type1 enum) previous-job-state (type1 enum) job-state-reasons (1setOf type2 keyword) job-state-reasons-added (1setOf type2 keyword) job-state-reasons-deleted (1setOf type2 keyword) [subscription-id** (integer(1:MAX))] ** If the Subscription object is implemented, the "subscription-id" MUST be supplied in the notification content. 4.2 Basic Printer Event Notification content: version-number status-code (with the value: basic-printer-event(601)) request-id (used as sequence number printer-uri-supported (uri) printer-trigger-event (type2 keyword) [printer-trigger-message* (text(255))] printer-trigger-time (integer(1:MAX)) [printer-trigger-date-time (dateTime)] printer-state (type1 enum) previous-printer-state (type1 enum) printer-state-reasons (1setOf type2 keyword) printer-state-reasons-added (1setOf type2 keyword) printer-state-reasons-deleted (1setOf type2 keyword) [subscription-id** (integer(1:MAX))] ** If the Subscription object is implemented, the "subscription-id" MUST be supplied in the notification content. 5 5 REQUIRED Job Submission Subscription As in the current notification spec (July 22, 1999), the usual method for a client to associate one subscription with a Job is to specify the subscription when the job is created. For a Job Submission Subscription, the client supplies the following notification operation attributes: notify-recipients (1setOf uri) REQUIRED to support [notify-events (1setOf type2 keyword)] REQUIRED to support [notify-user-data (octetString(255))] OPTIONAL to support 5.1 REQUIRED operation requests and responses related to notification This section lists the REQUIRED operation requests and response that have some relation to notification. The section 6 lists the OPTIONAL operation requests and responses associated with the OPTIONAL Subscription object. 5.1.1Job Creation Operations (Create-Job, Print-Job, Print-URI, and Validate-Job) The following IPP/1.1 extension operation attributes are defined for use with any of the job creation operations, including Validate-Job (which doesn't create a job or subscription): Request: Group 1: Operation Attributes ["notify-recipients" (1setOf uri) ["notify-events" (1setOf type2 keyword)] ["notify-user-data" (octetString(255))]] Response: Group 1: Operation Attributes 5.1.2Get-Printer-Attributes The Get-Printer-Attributes can be used to request the additional Printer Description attributes that indicate the notification supported. See section 3.1.1. 5.1.3Get-Printer-Subscriptions The Get-Printer-Subscriptions operations returns Printer subscription objects, i.e., ones associated with the Printer object or ones that have not been associated with either a Printer or Job object. Subscription objects that are associated with a Job object are not returned, since there could be a large number of them associated with a large number of jobs and the Job Subscription can be easily queried using the Get-Job- Attributes or Get-Jobs operations to request the "subscription-ids" attribute and then performing Get-Subscriptions operations. ISSUE 1: Agreed that we don't want this operation to return the Subscription objects associated with Jobs, correct? 6 Request: Group 1: Operation Attributes "attributes-charset" "attributes-natural-language" "printer-uri" (uri) ["requesting-user-name" (name(MAX))] ["limit" (integer(1:MAX))] ["requested-attributes" (1setOf type2 keyword)] ISSUE 2: or is it was simpler just to always return all of the attributes of the Subscription object and not have "requested- attributes"? ["my-subscriptions" (boolean)] Response: Group 1: Operation Attributes "status-code" (type2 enum) "attributes-charset" "attributes-natural-language" ["status-message" (text)] ["detailed-status-message" (text(MAX))] ["subscription-ids" (1setOf integer(1:MAX))] Group 2: Unsupported Attributes Group 3 to N: ISSUE 3: We don't really need a parallel Get-Job-Subscriptions operation, since a client can use either Get-Job-Attributes or Get-Jobs to request the Job's "subscription-ids" attribute and then do a Get- Subscription-Attributes for each, ok? 5.1.4Get-Job-Attributes The Get-Job-Attributes can be used to request the additional Job Description attributes that relate to notification. See section 3.1.2. 6 OPTIONAL Explicit Subscriptions and the Subscription object This section describes the new notification object model that adds a Subscription object which together with the Job and Printer object provide the notification semantics. The Subscription object is OPTIONAL. Without the Subscription object, the Job Submission Subscription semantics are supported with only a single subscription per job and no explicit Subscriptions for the Job or Printer object as described in section 5. 6.1 Object Relationships When the Subscription object is supported, it is created and associated with one Printer object, one previously created Job object, or neither (so that a subsequent job creation operation can perform the association of the Job object with the Subscription object and possibly other previously created Subscription objects). 7 The object relationships can be stated as follows: The Printer object contains zero or more Subscription objects A Subscription object is contained in one Printer object A Subscription object is exactly one of: associated with one Printer object (s1-s3) associated with one previously created Job object (s5 and s6 are associated with job j1 s7 is associated with job j2) not associated with either a Printer object or a Job object (s4) A Printer object is associated with zero or more Subscription objects (p1 is associated with s1-s3) A Job object is associated with zero or more previously created Subscription objects (j1 is associated with s5 and s6; j2 is associated with s7 j3 is not associated with any s objects) 8 A Subscription object cannot be contained in or associated with more than one Printer object A Subscription object cannot be associated with more than one Job object A Subscription object cannot be associated with both a Printer object and a Job object A Subscription object MUST be associated ONLY with jobs that are contained in its Printer object The object association relationships can be seen pictorially as (object containment not shown): Subscription objects Printer object +----+ +------------+ | s1 |<---------------------------------------------->| | +----++ | | | s2 |<--------------------------------------------->| p1 | +----++ | | | s3 |<-------------------------------------------->| | +----++ +------------+ | s4 | Job objects +----++ +------+ | s5 |<---------->| | +----++ | j1 | | s6 |<--------->| | +----++ +------++ | s7 |<--------->| | +----+ | j2 | | | +------++ | | | j3 | | | +------+ 6.2 Extensions to Job Submission Subscriptions for Subscription object Even when the Subscription object is supported, the usual method for a client to associate one subscription with a Job is to specify the subscription when the job is created. For a Job Submission Subscription, the client supplies the following notification operation attributes: notify-recipients (1setOf uri) REQUIRED to support [notify-events (1setOf type2 keyword)] REQUIRED to support [notify-user-data (octetString(255))] OPTIONAL to support If the implementation supports the Subscription operation, then the Printer MUST create a Subscription object, duplicate these notification operation attributes on it, and return subscription id of the Subscription object in the job creation response. Otherwise, the subscription couldn't be canceled for the job. If the implementation does not support the Subscription object, then the notification operation attributes remain only on the Job object. 9 If the client only supplies a "subscription-ids" attribute and does not supply these explicit "notify-xxx" attributes, the Printer MUST copy these three attributes from the first Subscription object identified in the "subscription-ids" operation attribute. Then all clients will see the subscription attributes of the first subscription on the Job object, thereby simplifying client query of job-related notification subscription information. When the client does not supply any "xxx- notify" operation attributes in the job creation operation, the Printer does not create any new Subscription objects. 6.3 Operation requests and responses related to the Subscription object This section lists the operation requests and responses the MUST be supported if the OPTIONAL Subscription object is supported and vice versa. 6.3.1Job Creation Operations (Create-Job, Print-Job, Print-URI, and Validate-Job) The following IPP/1.1 extension operation attributes are defined for use with any of the job creation operations, including Validate-Job (which doesn't create a job or subscription): Request: Group 1: Operation Attributes ["subscription-ids" (1setOf integer(1:MAX))] ["notify-recipients" (1setOf uri) ["notify-events" (1setOf type2 keyword)] ["notify-user-data" (octetString(255))]] Response: Group 1: Operation Attributes [subscription-ids (1setOf integer(1:MAX))] Notes: The client MAY supply one or both of: 1. one or more subscription ids for previously created (but unassociated) Subscription objects 2. explicit "notify-xxx" attributes If the implementation supports the Subscription object and the client supplies "notify-xxx" operation attributes, the Printer MUST create a new Subscription object initialized with these "notify-xxx" operation attributes and return the "subscription-ids" operation attribute with the new subscription-id as the first value. No lease time is requested or returned, since Subscription objects associated with Jobs have no real lease. Instead the Subscription object is maintained until the job completes and the document data is deleted. 10 6.3.2Create-Subscription Operation Request: Group 1: Operation Attributes "attributes-charset" (charset) "attributes-natural-language" (naturalLanguage) "printer-uri" (uri) ["requesting-user-name" (name(MAX))] "notify-recipients" (1setOf uri) ["notify-events" (1setOf type2 keyword)] ["notify-user-data" (octetString(255))] ["notify-lease-time" (integer(0:MAX))] ["associated-job-id" (integer(1:MAX)) OR "associated-printer" (boolean)] Response: Group 1: Operation Attributes "status-code" (type2 enum) "attributes-charset" (charset) "attributes-natural-language" (naturalLanguage ["status-message" (text(255))] ["detailed-status-message" (text(MAX)) "subscription-id" (integer(1:MAX)) "notify-lease-time" (integer(0:MAX)) "notify-lease-time-remaining" (integer(0:MAX)) Group 2: Unsupported Attributes Notes: A "notify-lease-time" and "notify-lease-time-remaining" of 0 means infinite for use with Subscriptions associated with Job objects, since the life of the subscription is the same as for the documents in the job. The client MUST supply either "associated-job-id" or "associated- printer" or neither one, but MUST NOT specify both, since a Subscription object can be associated with at most one (Job or Printer) object. The Printer object MUST return the "notify-lease-time" actually granted which may be less than the requester requested if it was greater than the MAX supported or more than the requester requested if it was less than the MIN supported, as indicated in the Printer's "lease-time- supported" (rangeOfInteger(0:MAX)) attribute. The Printer object MUST return the "notify-lease-time-remaining" which is the number of seconds remaining in the lease. 6.3.3Get-Subscription-Attributes The Get-Subscription-Attributes can be used to request the Subscription object attributes. See section 3.1.3. 11 Request: Group 1: Operation Attributes "attributes-charset" "attributes-natural-language" "printer-uri" (uri) ["job-id" (integer(1:MAX))] ["requesting-user-name" (name(MAX))] "subscription-id" (integer(1:MAX)) ["requested-attributes" (1setOf type2 keyword)] ISSUE 4: or is it simpler just to always return all of the attributes of the Subscription object, since there are not too many? Response: Group 1: Operation Attributes "status-code" (type2 enum) "status-message" (text) "attributes-charset" "attributes-natural-language" Group 2: Unsupported Attributes Group 3: Notes: A client MUST supply the "job-id" operation attribute, if the Subscription object is associated with a Job. If the "job-id" operation attribute is omitted, the "subscription-id" is assumed to apply to a Subscription object associated with the Printer object or not associated yet with either the Printer object or a Job object. 6.3.4Renew-Subscription Group 1: Operation Attributes "attributes-charset" "attributes-natural-language" "printer-uri" (uri) "requesting-user-name" (name(MAX)) "subscription-id" (integer(1:MAX)) "notify-lease-time" (integer(0:MAX)) Response: Group 1: Operation Attributes "status-code" (type2 enum) "attributes-charset" "attributes-natural-language" ["status-message" (text(255))] ["detailed-status-message" (text(MAX))] "notify-lease-time" (integer(0:MAX)) "notify-lease-time-remaining" (integer(0:MAX)) Group 2: Unsupported Attributes Notes: The Printer object MUST return the "notify-lease-time" actually granted which may be less than the requester requested if it was greater than the MAX supported or more than the requester requested if it was less than the MIN supported, as indicated in the Printer's "lease-time- supported" (rangeOfInteger(0:MAX)) attribute. The Printer object MUST return the "notify-lease-time-remaining" which is the number of seconds remaining in the lease. 12 6.3.5Cancel-Subscription Request: Group 1: Operation Attributes "attributes-charset" "attributes-natural-language" "printer-uri" (uri) ["job-id" (integer(1:MAX))] ["requesting-user-name" (name(MAX))] "subscription-id" (integer(1:MAX)) Response: Group 1: Operation Attributes "status-code" (type2 enum) "attributes-charset" "attributes-natural-language" ["status-message" (text(255))] ["detailed-status-message" (text(MAX))] Group 2: Unsupported Attributes Notes: A client MUST supply the "job-id" operation attribute, if the Subscription object is associated with a Job. If the "job-id" operation attribute is omitted, the "subscription-id" is assumed to apply to a Subscription object associated with the Printer object or not associated yet with either the Printer object or a Job object. 6.4 Subscription object lease time A Subscription object that is associated with a Printer object or is not associated with any object has a lease time. When the lease time expires, the Printer object MUST delete the Subscription object. A subscriber is expected to renew such Subscriptions before the lease expires. A Subscription object that is associated with a Job object has no lease; instead the Printer object deletes Subscription object when it deletes document data for the job. Thus if the job is in one of the Retained states ('completed', 'canceled', or 'aborted') and a client issues the Restart-Job or Reprocess-Job operation, the Printer initializes the associated Subscription objects with new lease times. A Subscription object that is associated with a Job does not have a lease. Instead the life of the job is used instead. When the Job completes (or is aborted or canceled), the documents may be retained for a period of time so that a client can use the Restart-Job or Reprocess- Job operation to perform the job again. In these cases, the subscription(s) associated with the Job are automatically renewed. When the Printer object deletes the Documents for a completed (aborted or canceled) Job, then it MUST also delete any Subscription objects associated with the Job. 6.5 Sequencing of Subscription object association with the Printer or a Job object Subscription object may be created before Job objects and vice versa. All associations between Subscription objects and a Printer or a Job object occurs when the second object instance is created by specifying 13 the first object instance that is to form the association. Therefore, one and only one of the following rules for the timing and sequencing of associating objects applies to each association: 1. A Subscription object is associated with its Printer object when the Subscription object is created 2. A Subscription object is associated with a previously created Job object when the Subscription object is created 3. A Subscription object is created without any association and a subsequent Job object creation associates the Job object with (one or more previously created, but unassociated) Subscription object(s) 6.6 Not implementing the Subscription object As an implementer option, only Job Submission Subscription need be supported. In this case, the Subscription object and the Create- Subscription, Cancel-Subscription, Renew-Subscription, and Get-Printer- Subscriptions operations are not implemented. Thus no Explicit subscriptions are provided. However, a Job Submission Subscription can still specify Job events and/or Printer events, just as when the Subscription object and the other operations are implemented. 14