IPP> NOT - IPP Notification Model with new OPTIONAL Subscription objec t

IPP> NOT - IPP Notification Model with new OPTIONAL Subscription objec t

Hastings, Tom N hastings at cp10.es.xerox.com
Mon Aug 2 23:09:14 EDT 1999


I've created a short (12-page) IPP Notification Model paper for discussion
on the DL and the IPP telecon, this Wednesday, 8/4/99, 10-12 PDT (1-3 EDT).
This model will allow us to agree on the model semantics for notification
before updating the detailed specification.  The .pdf is much more readable
and has line numbers.

ftp://ftp.pwg.org/pub/pwg/ipp/new_NOT/ipp-notification-model-990802.doc
ftp://ftp.pwg.org/pub/pwg/ipp/new_NOT/ipp-notification-model-990802.pdf
ftp://ftp.pwg.org/pub/pwg/ipp/new_NOT/ipp-notification-model-990802.txt

There are four issues embedded in the document:

ISSUE 1:  Agreed that we don't want the Get-Printer-Subscriptions operation
to return the
Subscription objects associated with Jobs, correct?

ISSUE 2:  or is it was simpler for the Get-Printer-Subscriptions operation
to always return all of the attributes of the Subscription object and not
have "requested-
attributes"?

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?

ISSUE 4: or is it simpler for the Get-Subscription-Attributes operation to
always 
return all of the attributes of the Subscription object, since there are not
too many?

Here is the plain text version of the document:

                         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


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":

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

       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:
               <the requested Subscription Attributes for each
Subscription object
               in a separate group>

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

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)

     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.

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.

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.

       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: <the requested Subscription object 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.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.

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




More information about the Ipp mailing list