draft-ietf-trade-voucher-vtsapi-00.txt   draft-ietf-trade-voucher-vtsapi-01.txt 
Trade Working Group July 2001 Trade Working Group January 2002
INTERNET-DRAFT Masayuki Terada INTERNET-DRAFT Masayuki Terada
Ko Fujimura Ko Fujimura
Expires: January 2002 NTT Expires: July 2002 NTT
Voucher Trading System Application Programming Interface (VTS-API) Voucher Trading System Application Programming Interface (VTS-API)
<draft-ietf-trade-voucher-vtsapi-00.txt> <draft-ietf-trade-voucher-vtsapi-01.txt>
Status of This Document Status of This Document
This document is an Internet-Draft and is in full conformance with This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026. all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet- other groups may also distribute working documents as Internet-
Drafts. Drafts.
skipping to change at page 2, line 5 skipping to change at page 10, line ?
Abstract Abstract
This document specifies the Voucher Trading System Application This document specifies the Voucher Trading System Application
Programming Interface (VTS-API). The VTS-API allows a wallet or other Programming Interface (VTS-API). The VTS-API allows a wallet or other
application to issue, transfer, and redeem vouchers in a uniform application to issue, transfer, and redeem vouchers in a uniform
manner independent of the VTS implementation. The VTS is a system to manner independent of the VTS implementation. The VTS is a system to
securely transfer vouchers, e.g., coupons, tickets, loyalty points, securely transfer vouchers, e.g., coupons, tickets, loyalty points,
and gift certificates; this process is often necessary in the course and gift certificates; this process is often necessary in the course
of payment and/or delivery transactions. of payment and/or delivery transactions.
M. Terada and K. Fujimura [Page 1]
Table of Contents Table of Contents
Status of this Memo . . . . . . . . . . . . . . . . . . . . . . . 1 Status of this Memo . . . . . . . . . . . . . . . . . . . . . . . 1
Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1 Abstract . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3
2. Processing Model . . . . . . . . . . . . . . . . . . . . . 3 2. Processing Model . . . . . . . . . . . . . . . . . . . . . 3
3. Design Overview . . . . . . . . . . . . . . . . . . . . . 5 3. Design Overview . . . . . . . . . . . . . . . . . . . . . 5
4. Concepts . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Concepts . . . . . . . . . . . . . . . . . . . . . . . . . 5
5. Interface Definitions . . . . . . . . . . . . . . . . . . 6 5. Interface Definitions . . . . . . . . . . . . . . . . . . 6
5.1 VTSManager . . . . . . . . . . . . . . . . . . . . . . . . 6 5.1 VTSManager . . . . . . . . . . . . . . . . . . . . . . . . 6
skipping to change at page 2, line 32 skipping to change at page 10, line ?
5.4 VTSAgent . . . . . . . . . . . . . . . . . . . . . . . . . 8 5.4 VTSAgent . . . . . . . . . . . . . . . . . . . . . . . . . 8
5.4.1 login . . . . . . . . . . . . . . . . . . . . . . . . . . 9 5.4.1 login . . . . . . . . . . . . . . . . . . . . . . . . . . 9
5.4.2 logout . . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.4.2 logout . . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.4.3 prepare . . . . . . . . . . . . . . . . . . . . . . . . . 10 5.4.3 prepare . . . . . . . . . . . . . . . . . . . . . . . . . 10
5.4.4 issue . . . . . . . . . . . . . . . . . . . . . . . . . . 11 5.4.4 issue . . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.4.5 transfer . . . . . . . . . . . . . . . . . . . . . . . . . 11 5.4.5 transfer . . . . . . . . . . . . . . . . . . . . . . . . . 11
5.4.6 consume . . . . . . . . . . . . . . . . . . . . . . . . . 12 5.4.6 consume . . . . . . . . . . . . . . . . . . . . . . . . . 12
5.4.7 present . . . . . . . . . . . . . . . . . . . . . . . . . 13 5.4.7 present . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.4.8 cancel . . . . . . . . . . . . . . . . . . . . . . . . . . 13 5.4.8 cancel . . . . . . . . . . . . . . . . . . . . . . . . . . 13
5.4.9 resume . . . . . . . . . . . . . . . . . . . . . . . . . . 14 5.4.9 resume . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.4.10 getContents . . . . . . . . . . . . . . . . . . . . . . . 14 5.4.10 create . . . . . . . . . . . . . . . . . . . . . . . . . . 14
5.4.11 getSessions . . . . . . . . . . . . . . . . . . . . . . . 15 5.4.11 delete . . . . . . . . . . . . . . . . . . . . . . . . . . 15
5.4.12 addReceptionListener . . . . . . . . . . . . . . . . . . . 15 5.4.12 getContents . . . . . . . . . . . . . . . . . . . . . . . 15
5.4.13 removeReceiptListener . . . . . . . . . . . . . . . . . . 15 5.4.13 getSessions . . . . . . . . . . . . . . . . . . . . . . . 15
5.5 Session . . . . . . . . . . . . . . . . . . . . . . . . . 16 5.4.14 getLog . . . . . . . . . . . . . . . . . . . . . . . . . . 16
5.5.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 16 5.4.15 addReceptionListener . . . . . . . . . . . . . . . . . . . 16
5.5.2 getVoucher . . . . . . . . . . . . . . . . . . . . . . . . 16 5.4.16 removeReceptionListener . . . . . . . . . . . . . . . . . 16
5.5.3 getSender . . . . . . . . . . . . . . . . . . . . . . . . 16 5.5 Session . . . . . . . . . . . . . . . . . . . . . . . . . 17
5.5.4 getReceiver . . . . . . . . . . . . . . . . . . . . . . . 17 5.5.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 17
5.5.5 isPrepared . . . . . . . . . . . . . . . . . . . . . . . . 17 5.5.2 getVoucher . . . . . . . . . . . . . . . . . . . . . . . . 17
5.5.6 isActivated . . . . . . . . . . . . . . . . . . . . . . . 17 5.5.3 getSender . . . . . . . . . . . . . . . . . . . . . . . . 17
5.5.7 isSuspended . . . . . . . . . . . . . . . . . . . . . . . 17 5.5.4 getReceiver . . . . . . . . . . . . . . . . . . . . . . . 18
5.5.8 isCompleted . . . . . . . . . . . . . . . . . . . . . . . 17 5.5.5 isPrepared . . . . . . . . . . . . . . . . . . . . . . . . 18
5.6 Voucher . . . . . . . . . . . . . . . . . . . . . . . . . 17 5.5.6 isActivated . . . . . . . . . . . . . . . . . . . . . . . 18
5.6.1 getIssuer . . . . . . . . . . . . . . . . . . . . . . . . 18 5.5.7 isSuspended . . . . . . . . . . . . . . . . . . . . . . . 18
5.6.2 getPromise . . . . . . . . . . . . . . . . . . . . . . . 18 5.5.8 isCompleted . . . . . . . . . . . . . . . . . . . . . . . 18
5.6.3 getCount . . . . . . . . . . . . . . . . . . . . . . . . . 18 5.6 Voucher . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.7 VoucherComponentRepository . . . . . . . . . . . . . . . . 18 5.6.1 getIssuer . . . . . . . . . . . . . . . . . . . . . . . . 19
5.7.1 regist . . . . . . . . . . . . . . . . . . . . . . . . . 18 5.6.2 getPromise . . . . . . . . . . . . . . . . . . . . . . . 19
5.8 VoucherComponent . . . . . . . . . . . . . . . . . . . . . 19 5.6.3 getCount . . . . . . . . . . . . . . . . . . . . . . . . . 19
5.8.1 getDocument . . . . . . . . . . . . . . . . . . . . . . . 19 5.7 VoucherComponentRepository . . . . . . . . . . . . . . . . 19
5.9 ReceptionListener . . . . . . . . . . . . . . . . . . . . 20 5.7.1 register . . . . . . . . . . . . . . . . . . . . . . . . . 20
5.9.1 arrive . . . . . . . . . . . . . . . . . . . . . . . . . . 20 5.8 VoucherComponent . . . . . . . . . . . . . . . . . . . . . 20
5.10 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . 20 5.8.1 getIdentifier . . . . . . . . . . . . . . . . . . . . . . 20
6. Example Code . . . . . . . . . . . . . . . . . . . . . . . 21 5.8.2 getDocument . . . . . . . . . . . . . . . . . . . . . . . 21
7. Security Considerations . . . . . . . . . . . . . . . . . 22 5.9 ReceptionListener . . . . . . . . . . . . . . . . . . . . 21
8. Acknowledgement . . . . . . . . . . . . . . . . . . . . . 23
9. References . . . . . . . . . . . . . . . . . . . . . . . . 23 M. Terada and K. Fujimura [Page 2]
10. Author's Address . . . . . . . . . . . . . . . . . . . . . 23 5.9.1 arrive . . . . . . . . . . . . . . . . . . . . . . . . . . 21
5.10 Exceptions . . . . . . . . . . . . . . . . . . . . . . . . 22
6. Example Code . . . . . . . . . . . . . . . . . . . . . . . 23
7. Security Considerations . . . . . . . . . . . . . . . . . 24
8. Acknowledgement . . . . . . . . . . . . . . . . . . . . . 24
9. References . . . . . . . . . . . . . . . . . . . . . . . . 24
10. Author's Address . . . . . . . . . . . . . . . . . . . . . 25
1. Introduction 1. Introduction
This document specifies the Voucher Trading System Application This document specifies the Voucher Trading System Application
Programming Interface (VTS-API). The motivation and background of the Programming Interface (VTS-API). The motivation and background of the
Voucher Trading System (VTS) are described in Requirements for Voucher Trading System (VTS) are described in Requirements for
Generic Voucher Trading [GVT]. Generic Voucher Trading [VTS].
A voucher is a logical entity that represents a certain right and is A voucher is a logical entity that represents a certain right and is
logically managed by the VTS. A voucher is generated by the issuer, logically managed by the VTS. A voucher is generated by the issuer,
traded among users, and finally collected using VTS. The terminology traded among users, and finally collected using VTS. The terminology
and model of the VTS are also described in [GVT]. and model of the VTS are also described in [VTS].
The VTS-API allows a caller application to issue, transfer, and The VTS-API allows a caller application to issue, transfer, and
redeem vouchers in a uniform manner independent of the VTS redeem vouchers in a uniform manner independent of the VTS
implementation. Several attempts have been made at providing a implementation. Several attempts have been made at providing a
generic payment API. Java Commerce Client [JCC] and Generic Payment generic payment API. Java Commerce Client [JCC] and Generic Payment
Service Framework [GPSF], for example, introduce a modular wallet Service Framework [GPSF], for example, introduce a modular wallet
architecture that permits diverse types of payment modules to be architecture that permits diverse types of payment modules to be
added as plug-ins and supports both check-like/cash-like payment added as plug-ins and supports both check-like/cash-like payment
models. This document is inspired by these approaches but the scope models. This document is inspired by these approaches but the scope
of this document is limited to the VTS model, in which cash-like of this document is limited to the VTS model, in which cash-like
skipping to change at page 3, line 43 skipping to change at page 10, line ?
Unlike the APIs provided in JCC and GPSF, which are designed to Unlike the APIs provided in JCC and GPSF, which are designed to
transfer only monetary values, this API enables the transfer of a transfer only monetary values, this API enables the transfer of a
wide-range of values through the use of XML-based Generic Voucher wide-range of values through the use of XML-based Generic Voucher
Language [GVL]. The monetary meaning of the voucher is interpreted by Language [GVL]. The monetary meaning of the voucher is interpreted by
the upper application layer using the information described in the the upper application layer using the information described in the
language. This approach makes it possible to provide a simpler API in language. This approach makes it possible to provide a simpler API in
the voucher-transfer layer and enhances runtime efficiency. the voucher-transfer layer and enhances runtime efficiency.
The API specification in this document is described in the Java The API specification in this document is described in the Java
language syntax. Bindings for other programming languages are to be language syntax. Bindings for other programming languages may be
completed in a future version of this document or separate related completed in a future version of this document or separate related
specifications. [Editor's note: Language independent interface specifications. [Editor's note: Language independent interface
definitions, e.g., CORBA IDL, can be used if needed, but we are not definitions, e.g., CORBA IDL, can be used if needed, but we are not
sure if they atr really language independent.] sure if they are really language independent.]
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in
this document are to be interpreted as described in [RFC 2119] this document are to be interpreted as described in [RFC 2119]
M. Terada and K. Fujimura [Page 3]
2. Processing Model 2. Processing Model
This section provides the processing model in which the VTS-API is This section provides the processing model in which the VTS-API is
used. Most of the text in this section has been taken from the used. Most of the text in this section has been taken from the
Generic Voucher Language specification [GVL]. Generic Voucher Language specification [GVL].
There are several ways of implementing VTS. For discount coupons or There are several ways of implementing VTS. For discount coupons or
event tickets, for example, the smart-card-based decentralized event tickets, for example, the smart-card-based decentralized
offline VTS is often preferred, whereas for bonds or securities, offline VTS is often preferred, whereas for bonds or securities,
the centralized online VTS is preferred. It is impractical to the centralized online VTS is preferred. It is impractical to
skipping to change at page 4, line 53 skipping to change at page 10, line ?
(*2) If a listener is registered. (*2) If a listener is registered.
Figure 1. Wallet architecture with VTS plug-ins Figure 1. Wallet architecture with VTS plug-ins
After sender and receiver agree on what vouchers are to be traded and After sender and receiver agree on what vouchers are to be traded and
which VTS is to be used, the issuing system or wallet system requests which VTS is to be used, the issuing system or wallet system requests
the corresponding VTS plug-in to permit the issue, transfer, or the corresponding VTS plug-in to permit the issue, transfer, or
redeem transactions to be performed via the VTS-API. The VTS then redeem transactions to be performed via the VTS-API. The VTS then
rewrites the ownership of the vouchers using the VTS-specific rewrites the ownership of the vouchers using the VTS-specific
protocol. Finally, a completion event is sent to the wallet systems protocol. Finally, a completion event is sent to the wallet systems
M. Terada and K. Fujimura [Page 4]
or issuing/collecting systems. or issuing/collecting systems.
This document describes the VTS-API specification. See [GVL] for the This document describes the VTS-API specification. See [GVL] for the
Voucher Component specification. Voucher Component specification.
3. Design Overview 3. Design Overview
We have adopted the following approach to specify the VTS-API. We have adopted the following approach to specify the VTS-API.
1) Provide an abstract and uniform API that encapsulates the VTS 1) Provide an abstract and uniform API that encapsulates the VTS
skipping to change at page 5, line 34 skipping to change at page 10, line ?
other standards, e.g., [IOTP] or [ECML], if necessary. other standards, e.g., [IOTP] or [ECML], if necessary.
4) Support only push-type voucher transfer interface in which voucher 4) Support only push-type voucher transfer interface in which voucher
transfer session is initiated by the transferor side. Pull-type transfer session is initiated by the transferor side. Pull-type
voucher transfer interface can be implemented on top of the voucher transfer interface can be implemented on top of the
push-type VTS interface at application level. push-type VTS interface at application level.
4. Concepts 4. Concepts
The VTS-API consists of the following interfaces. A VTS is required The VTS-API consists of the following interfaces. A VTS is required
to implement all of the interfaces except ReceiptionLister, which to implement all of the interfaces except ReceptionLister, which is
is intended to be implemented by wallets or other applications that intended to be implemented by wallets or other applications that
use VTS. use VTS.
VTSManager VTSManager
Provides the starting point to use a VTS plug-in. All of the Provides the starting point to use a VTS plug-in. All of the
objects needed to manipulate vouchers can be directly or indirectly objects needed to manipulate vouchers can be directly or indirectly
acquired via the VTSManager. A VTSManager maintains the two acquired via the VTSManager. A VTSManager maintains the two
repositories; a ParticipantRepository and a repositories; a ParticipantRepository and a
VoucherComponentRepository described below. VoucherComponentRepository described below.
ParticipantRepository ParticipantRepository
Provides the access points of Participants, which are to be trading Provides the access points of Participants, which are to be trading
partners. A ParticipantRepository maintains Participants and acts as partners. A ParticipantRepository maintains Participants and acts as
an "address book" of trading partners. an "address book" of trading partners.
Participant Participant
M. Terada and K. Fujimura [Page 5]
Represents a participant (such as issuers, holders, and Represents a participant (such as issuers, holders, and
collectors). A Participant knows how to obtain the corresponding collectors). A Participant knows how to obtain the corresponding
VTSAgent described below. VTSAgent described below.
VTSAgent (extends Participant) VTSAgent (extends Participant)
Provides the access point of vouchers in Valid Voucher Set (VVS) Provides the access point of vouchers in Valid Voucher Set (VVS)
that is logically managed by VTS. A VTSAgent provides a means of that is logically managed by VTS. A VTSAgent provides a means of
manipulating vouchers held by its holder; basic trading methods, manipulating vouchers held by its holder; basic trading methods,
i.e., issue, transfer, consume, and present. Before calling trading i.e., issue, transfer, consume, and present. Before calling trading
skipping to change at page 6, line 53 skipping to change at page 10, line ?
ReceptionListener ReceptionListener
Provides a listener function with regard to the receipt of a voucher Provides a listener function with regard to the receipt of a voucher
by VTSAgent to wallets or other applications that implement this by VTSAgent to wallets or other applications that implement this
interface. (This interface may not be implemented as part of VTS) interface. (This interface may not be implemented as part of VTS)
5. Interface Definitions 5. Interface Definitions
The interfaces defined in this document reside in the package named The interfaces defined in this document reside in the package named
M. Terada and K. Fujimura [Page 6]
"org.ietf.vts". Wallets or other applications that use this "org.ietf.vts". Wallets or other applications that use this
API,should import this package as "import org.ietf.vts.*;". API,should import this package as "import org.ietf.vts.*;".
5.1 VTSManager 5.1 VTSManager
public interface VTSManager public interface VTSManager
Provides the starting point to use a VTS plug-in. Provides the starting point to use a VTS plug-in.
All of the objects needed to manipulate vouchers can be directly or All of the objects needed to manipulate vouchers can be directly or
indirectly acquired via a VTSManager, so that wallets or other indirectly acquired via a VTSManager, so that wallets or other
applications can make the VTS available by instantiating an object applications can make the VTS available by instantiating an object
implementing this interface. implementing this interface.
Classes that implement this interface should have a public default Classes that implement this interface should have a public default
skipping to change at page 7, line 52 skipping to change at page 10, line ?
Provides the access points of Participants. A ParticipantRepository Provides the access points of Participants. A ParticipantRepository
maintains Participants and acts as an "address book" of trading maintains Participants and acts as an "address book" of trading
partners. partners.
The object implementing this interface maintains Participants (or The object implementing this interface maintains Participants (or
holds a reference to an object maintaining Participants), which are holds a reference to an object maintaining Participants), which are
to be trading partners. to be trading partners.
The implementation of ParticipantRepository may be either (an adaptor The implementation of ParticipantRepository may be either (an adaptor
M. Terada and K. Fujimura [Page 7]
to) "yellow pages" which is a network-wide directory service like to) "yellow pages" which is a network-wide directory service like
LDAP, or "pocket address book" which maintains only personal LDAP, or "pocket address book" which maintains only personal
acquaintances. acquaintances.
5.2.1 lookup 5.2.1 lookup
public Participant lookup(String id) public Participant lookup(String id)
Retrieves the participant that has the specified id. Retrieves the participant that has the specified id.
skipping to change at page 8, line 54 skipping to change at page 10, line ?
VTSAgent getVTSAgent() VTSAgent getVTSAgent()
Returns a VTSAgent, whose identifier is the same as the identifier of Returns a VTSAgent, whose identifier is the same as the identifier of
the participant. the participant.
Returns: Returns:
an object implementing VTSAgent. an object implementing VTSAgent.
M. Terada and K. Fujimura [Page 8]
5.4 VTSAgent 5.4 VTSAgent
public interface VTSAgent extends Participant public interface VTSAgent extends Participant
Represents contact points to access vouchers in Valid Voucher Set Represents contact points to access vouchers in Valid Voucher Set
(VVS) that is managed by the VTS. (VVS) that is managed by the VTS.
Each VTSAgent is associated with a holder and provides a means for Each VTSAgent is associated with a holder and provides a means for
managing vouchers owned by the holder. The holder must be managing vouchers owned by the holder. The holder must be
authenticated using login() method before be called by any other authenticated using the login() method before being called by any
method, or VTSSecurityException will be issue. other method, or VTSSecurityException will be issue.
Before calling any trading method, i.e., issue(), transfer(), Before calling any trading method, i.e., issue(), transfer(),
consume(), and present(), the application must establish a session by consume(), and present(), the application must establish a session by
the prepare() method. the prepare() method.
Sessions may often be suspended due to network failure when the Sessions may often be suspended due to network failure when the
voucher is sent via a network. The suspended sessions can be voucher is sent via a network. The suspended sessions can be
restarted by the resume() method. Details on the state management of restarted by the resume() method. Details on the state management of
a session are described in Section 5.5. a session are described in Section 5.5.
skipping to change at page 9, line 53 skipping to change at page 10, line ?
VTS), and returns the response from the smartcard to the server. VTS), and returns the response from the smartcard to the server.
Note that a PIN to unlock the smartcard may be given through this Note that a PIN to unlock the smartcard may be given through this
method depending on the implementation. method depending on the implementation.
3) Each user holds their own smartcard in which their own vouchers 3) Each user holds their own smartcard in which their own vouchers
are stored (decentralized VVS). In this case, the passphrase may are stored (decentralized VVS). In this case, the passphrase may
be null since no authentication is required. Note that a PIN to be null since no authentication is required. Note that a PIN to
unlock the smartcard may be given through this depends on the unlock the smartcard may be given through this depends on the
implementation. implementation.
M. Terada and K. Fujimura [Page 9]
Throws: Throws:
VTSSecurityException - if authentication fails. VTSSecurityException - if authentication fails.
5.4.2 logout 5.4.2 logout
public void logout() public void logout()
throws VTSException throws VTSException
Voids the authentication performed by the login() method. Voids the authentication performed by the login() method.
skipping to change at page 14, line 4 skipping to change at page 14, line 7
VTSSecurityException - if the VTSAgent cannot be authenticated VTSSecurityException - if the VTSAgent cannot be authenticated
correctly. correctly.
InsufficientVoucherException - if the VTSAgent doesn't have a InsufficientVoucherException - if the VTSAgent doesn't have a
sufficient number of vouchers to present. sufficient number of vouchers to present.
InvalidStateException - if the session is not "prepared". InvalidStateException - if the session is not "prepared".
CannotProceedException - if the transaction cannot be successfully CannotProceedException - if the transaction cannot be successfully
completed. completed.
5.4.8 cancel 5.4.8 cancel
public void cancel(Session session) public void cancel(Session session)
throws VTSException throws VTSException
Releases the session. "Prepared" sessions MUST be cancelled. An Releases the session. "Prepared" sessions MUST be canceled. An
implementation MAY be permitted to cancel "activated" or "suspended" implementation MAY be permitted to cancel "activated" or "suspended"
sessions. sessions.
Throws: Throws:
VTSSecurityException - if the VTSAgent cannot be authenticated VTSSecurityException - if the VTSAgent cannot be authenticated
correctly. correctly.
InvalidStateException - if the state of the session isn't InvalidStateException - if the state of the session isn't
cancellable. cancelable.
5.4.9 resume 5.4.9 resume
public void resume(Session session) public void resume(Session session)
throws VTSException throws VTSException
Restarts the session. Only "suspended" sessions can be resumed. Restarts the session. Only "suspended" sessions can be resumed.
The state of the session will be re-"activated" immediately, and it The state of the session will be re-"activated" immediately, and it
will be "completed" when the transaction is successfully completed or will be "completed" when the transaction is successfully completed or
skipping to change at page 14, line 38 skipping to change at page 14, line 42
network failures). network failures).
Throws: Throws:
VTSSecurityException - if the VTSAgent cannot be authenticated VTSSecurityException - if the VTSAgent cannot be authenticated
correctly. correctly.
InvalidStateException - if the session is not "suspended". InvalidStateException - if the session is not "suspended".
CannotProceedException - if the transaction cannot be successfully CannotProceedException - if the transaction cannot be successfully
completed. completed.
5.4.10 getContents 5.4.10 create
public void create(VoucherComponent promise, java.lang.Number num)
throws VTSException
Creates vouchers where the issuer is the VTSAgent itself. This
method creates the specified number of vouchers <this, promise,
this> and adds them to the VVS. Nothing is performed if the
specified number is 0.
Throws:
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
5.4.11 delete
public void delete(Participant issuer,
VoucherComponent promise,
java.lang.Number num)
throws VTSException
Deletes vouchers. This method deletes the specified number of
vouchers <issuer, promise, this> from the VVS. The VTSAgent must
have sufficient vouchers in the VVS. Nothing is performed if the
specified number is 0.
Throws:
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
InsufficientVoucherException - if the VTSAgent doesn't have
sufficient number of vouchers to delete.
5.4.12 getContents
public java.util.Set getContents(Participant issuer, public java.util.Set getContents(Participant issuer,
VoucherComponent promise) VoucherComponent promise)
throws VTSException throws VTSException
Returns the set of vouchers whose issuer and promise both match the Returns the set of vouchers whose issuer and promise both match the
issuer and promise specified in the parameters. issuer and promise specified in the parameters.
If null is specified for the issuer or promise parameter, it If null is specified for the issuer or promise parameter, it
indicates "any issuer" or "any promise", respectively. If null is indicates "any issuer" or "any promise", respectively. If null is
skipping to change at page 15, line 8 skipping to change at page 15, line 47
Returns: Returns:
the set of vouchers held by the holder of the VTSAgent. the set of vouchers held by the holder of the VTSAgent.
Throws: Throws:
VTSSecurityException - if the VTSAgent cannot be authenticated VTSSecurityException - if the VTSAgent cannot be authenticated
correctly. correctly.
5.4.11 getSessions 5.4.13 getSessions
public java.lang.Set getSessions() public java.lang.Set getSessions()
throws VTSException throws VTSException
Returns a set of not-completed sessions prepared by the VTSAgent. Returns a set of not-completed sessions prepared by the VTSAgent.
Returns: Returns:
the set of sessions prepared by the VTSAgent and not the set of sessions prepared by the VTSAgent and not yet completed.
yet completed.
Throws: Throws:
VTSSecurityException - if the VTSAgent cannot be authenticated VTSSecurityException - if the VTSAgent cannot be authenticated
correctly. correctly.
5.4.12 addReceptionListener 5.4.14 getLog
public void addReceiptListener(ReceiptListener l) public java.lang.Set getLog()
throws VTSException throws VTSException
Adds a ReceiptListener to the listener list. Returns a set of completed sessions prepared or received by the
VTSAgent. This set represents the trading log of the VTSAgent. A
VTS may delete an old log eventually, so that the entire log may
not be returned; the amount of the log kept by the VTSAgent is
implementation-specific.
After a ReceiptListener l is registered by this method, l.arrive() Returns:
the set of completed sessions prepared or received by the VTSAgent.
Throws:
VTSSecurityException - if the VTSAgent cannot be authenticated
correctly.
5.4.15 addReceptionListener
public void addReceptionListener(ReceptionListener l)
throws VTSException
Adds a ReceptionListener to the listener list.
After a ReceptionListener l is registered by this method, l.arrive()
will be called whenever the VTSAgent receives a voucher. will be called whenever the VTSAgent receives a voucher.
Nothing is performed if the specified listener is null. Nothing is performed if the specified listener is null.
Throws: Throws:
VTSSecurityException - if the VTSAgent cannot be authenticated VTSSecurityException - if the VTSAgent cannot be authenticated
correctly. correctly.
5.4.13 removeReceiptListener 5.4.16 removeReceptionListener
public void removeReceiptListener(ReceiptListener l) public void removeReceptionListener(ReceptionListener l)
throws VTSException throws VTSException
Removes a ReceiptListener from the listener list. Removes a ReceptionListener from the listener list.
Nothing is performed when the specified listener is null or not Nothing is performed when the specified listener is null or not
registered. registered.
Throws: Throws:
VTSSecurityException - if the VTSAgent cannot be authenticated VTSSecurityException - if the VTSAgent cannot be authenticated
correctly. correctly.
5.5 Session 5.5 Session
skipping to change at page 16, line 21 skipping to change at page 17, line 26
A session has four states: prepared, activated, suspended, and A session has four states: prepared, activated, suspended, and
completed. The initial state of a session is "prepared", and the completed. The initial state of a session is "prepared", and the
session will be "activated" immediately when any of the trading session will be "activated" immediately when any of the trading
methods of VTSAgent is called. The "activated" session will be methods of VTSAgent is called. The "activated" session will be
"completed" after the trading method is successfully completed. If "completed" after the trading method is successfully completed. If
the trading method is transiently failed (e.g. network failure), the the trading method is transiently failed (e.g. network failure), the
session will be "suspended". Suspended sessions can be re-"activated" session will be "suspended". Suspended sessions can be re-"activated"
and restarted by calling VTSAgent#resume(). and restarted by calling VTSAgent#resume().
A completed session may be disapeared from the VTSAgent; the session A completed session may disappear from the VTSAgent; the session
will be collected by the GC unless other objects keep its reference. will be collected by the GC unless other objects keep its reference.
5.5.1 getIdentifier 5.5.1 getIdentifier
public String getIdentifier() public String getIdentifier()
Returns the identifier of the session. The generation scheme of the Returns the identifier of the session. The generation scheme of the
identifier is implementation-specific. An implementation may use a identifier is implementation-specific. An implementation may use a
transaction ID as the identifier of the session. transaction ID as the identifier of the session.
skipping to change at page 18, line 4 skipping to change at page 19, line 10
public boolean isCompleted() public boolean isCompleted()
Verifies if the session is "completed". Verifies if the session is "completed".
Returns: Returns:
true if the session is in "completed" state, or false. true if the session is in "completed" state, or false.
5.6 Voucher 5.6 Voucher
public interface Voucher public interface Voucher
Represents voucher(s) described in [GVT]. An object implementing Represents voucher(s) described in [VTS]. An object implementing
this interface can represent more than one voucher if all of the this interface can represent more than one voucher if all of the
issuer part and the promise part of the vouchers are the same. issuer part and the promise part of the vouchers are the same.
5.6.1 getIssuer 5.6.1 getIssuer
public Participant getIssuer() public Participant getIssuer()
Returns the issuer part of the voucher(s). Returns the issuer part of the voucher(s).
Returns: Returns:
skipping to change at page 18, line 55 skipping to change at page 20, line 8
An object implementing VoucherComponentRepository provides a means of An object implementing VoucherComponentRepository provides a means of
retrieving the voucher components that are the promises of vouchers retrieving the voucher components that are the promises of vouchers
in the VVS. in the VVS.
Before issuing a voucher, the promise of the voucher must be Before issuing a voucher, the promise of the voucher must be
registered with this repository. The repository can be implemented registered with this repository. The repository can be implemented
as either a network-wide directory service or personal storage like as either a network-wide directory service or personal storage like
the ParticipantRepository. the ParticipantRepository.
5.7.1 regist 5.7.1 register
public VoucherComponent regist(org.w3c.dom.Document document)
public VoucherComponent register(org.w3c.dom.Document document)
Creates a voucher component associated with the specified DOM object Creates a voucher component associated with the specified DOM object
and registers the voucher component with the repository. and registers the voucher component with the repository.
A voucher component of the voucher to be issued must be registered A voucher component of the voucher to be issued must be registered
using this method. using this method.
Nothing is performed (and the method returns null) if the specified Nothing is performed (and the method returns null) if the specified
document is null or the syntax of the document does not conform to document is null or the syntax of the document does not conform to
the VTS. the VTS.
skipping to change at page 19, line 40 skipping to change at page 20, line 46
associated with an XML document that describes the promise made by associated with an XML document that describes the promise made by
the issuer of the voucher, e.g., the goods or services can be claimed the issuer of the voucher, e.g., the goods or services can be claimed
in exchange for redeeming the voucher. in exchange for redeeming the voucher.
This interface can be implemented as sort of a "smart pointer" to the This interface can be implemented as sort of a "smart pointer" to the
XML document. An implementation may have a reference to a voucher XML document. An implementation may have a reference to a voucher
component repository instead of the voucher component and retrieve component repository instead of the voucher component and retrieve
the document dynamically from the repository when the getDocument() the document dynamically from the repository when the getDocument()
method is called. method is called.
5.8.1 getDocument 5.8.1 getIdentifier
public String getIdentifier()
Returns the identifier of the voucher component. Each voucher
component must have a unique identifier. The identifier may be
used to check for equivalence of voucher components.
The format of the identifier is implementation-specific.
Returns:
The identifier string of the voucher component.
5.8.2 getDocument
public org.w3c.dom.Document getDocument() public org.w3c.dom.Document getDocument()
Returns a Document Object Model [DOM] representation of the document Returns a Document Object Model [DOM] representation of the document
associated with the voucher component by the associated with the voucher component by the
VoucherComponentRepository#regist() method. VoucherComponentRepository#register() method.
The DOM object to be returned may be retrieved from a The DOM object to be returned may be retrieved from a
VoucherComponentRepository on demand, instead of the VoucherComponent VoucherComponentRepository on demand, instead of the VoucherComponent
always keeping a reference to the DOM object. always keeping a reference to the DOM object.
Returns: Returns:
a DOM representation of the document assoiated with the voucher a DOM representation of the document associated with the voucher
component. component.
Throws: Throws:
DocumentNotFoundException - if the associated DOM object cannot be DocumentNotFoundException - if the associated DOM object cannot be
retrieved. retrieved.
5.9 ReceptionListener 5.9 ReceptionListener
public interface ReceptionListener extends java.util.EventListener public interface ReceptionListener extends java.util.EventListener
skipping to change at page 20, line 33 skipping to change at page 21, line 54
that "You have new vouchers", so that this interface may be that "You have new vouchers", so that this interface may be
implemented by wallets or other applications using VTS. implemented by wallets or other applications using VTS.
5.9.1 arrive 5.9.1 arrive
public void arrive(Session session) public void arrive(Session session)
Provides notification of the arrival of a voucher. Provides notification of the arrival of a voucher.
After the listener is registered to a VTSAgent (by the After the listener is registered to a VTSAgent (by the
VTSAgent#addReceiptionListener() method), the VTSAgent invokes this VTSAgent#addReceptionListener() method), the VTSAgent invokes this
method whenever it receives a voucher. method whenever it receives a voucher.
The specified session is equivalent to the session used by the sender The specified session is equivalent to the session used by the sender
to trade the voucher. The state of the session is "completed" when to trade the voucher. The state of the session is "completed" when
this method is called. this method is called.
5.10 Exceptions 5.10 Exceptions
java.lang.Exception java.lang.Exception
+-- VTSException +-- VTSException
skipping to change at page 21, line 44 skipping to change at page 23, line 16
// Issue a voucher // Issue a voucher
VTSManager vts = new FooVTSManager(); VTSManager vts = new FooVTSManager();
ParticipantRepository addrBook = vts.getParticipantRepository(); ParticipantRepository addrBook = vts.getParticipantRepository();
VoucherComponentRepository vcr = vts.getVoucherComponentRepository(); VoucherComponentRepository vcr = vts.getVoucherComponentRepository();
Participant you = addrBook.lookup("http://foo.bar/baz"); Participant you = addrBook.lookup("http://foo.bar/baz");
VTSAgent me = addrBook.lookup("myName").getVTSAgent(); VTSAgent me = addrBook.lookup("myName").getVTSAgent();
VoucherComponent promise = vcr.regist(anXMLVoucherDocument); VoucherComponent promise = vcr.register(anXMLVoucherDocument);
try { try {
me.login(); me.login();
s = me.prepare(you); s = me.prepare(you);
me.issue(s, promise, 1); me.issue(s, promise, 1);
me.logout(); me.logout();
} catch (VTSException e) { } catch (VTSException e) {
System.err.println("Sorry!"); System.err.println("Sorry!");
e.printStackTrace(); e.printStackTrace();
} }
skipping to change at page 22, line 34 skipping to change at page 24, line 4
System.err.println("Sorry!"); System.err.println("Sorry!");
e.printStackTrace(); e.printStackTrace();
} }
// Register an incoming voucher notifier (biff) // Register an incoming voucher notifier (biff)
VTSManager vts = new FooVTSManager(); VTSManager vts = new FooVTSManager();
ParticipantRepository addrBook = vts.getParticipantRepository(); ParticipantRepository addrBook = vts.getParticipantRepository();
VTSAgent me = addrBook.lookup("myName").getVTSAgent(); VTSAgent me = addrBook.lookup("myName").getVTSAgent();
ReceptionListener listener = new ReceptionListener() {
ReceiptionListener listener = new ReceiptionListener() {
public void arrive(Session s) { public void arrive(Session s) {
System.out.println("You got a new voucher."); System.out.println("You got a new voucher.");
} }
}; };
try { try {
me.login(); me.login();
me.addReceiptionListener(listener); me.addReceptionListener(listener);
me.logout(); me.logout();
} catch (VTSException e) { } catch (VTSException e) {
System.err.println("Sorry!"); System.err.println("Sorry!");
e.printStackTrace(); e.printStackTrace();
} }
7. Security Considerations 7. Security Considerations
This document assumes that the VTS plug-in is trusted. The caller This document assumes that the VTS plug-in is trusted. The caller
application of a VTS should authenticate the VTS plug-in and bind it application of a VTS should authenticate the VTS plug-in and bind it
skipping to change at page 23, line 26 skipping to change at page 24, line 48
9. References 9. References
[DOM] "Document Object Model (DOM), Level 1 Specification", October [DOM] "Document Object Model (DOM), Level 1 Specification", October
<http://www.w3.org/TR/REC-DOM-Level-1/>,1998. <http://www.w3.org/TR/REC-DOM-Level-1/>,1998.
[DOMHash] H. Maruyama, K. Tamura, and N. Uramoto, "Digest Values [DOMHash] H. Maruyama, K. Tamura, and N. Uramoto, "Digest Values
for DOM (DOMHASH)", RFC 2803, 2000. for DOM (DOMHASH)", RFC 2803, 2000.
[ECML] J. W. Parsons, "Electronic Commerce Modeling Language (ECML) [ECML] J. W. Parsons, "Electronic Commerce Modeling Language (ECML)
Version 2 Specification", draft-ietf-trade-ecml2-spec-00.txt, Version 2 Specification", draft-ietf-trade-ecml2-spec-02.txt,
2001. 2001.
[GPSF] G. Lacoste, B. Pfitzmann, M. Steiner, and M. Waidner (Eds.), [GPSF] G. Lacoste, B. Pfitzmann, M. Steiner, and M. Waidner (Eds.),
"SEMPER - Secure Electronic Marketplace for Europe," LNCS 1854, "SEMPER - Secure Electronic Marketplace for Europe," LNCS 1854,
Springer-Verlag, 2000. Springer-Verlag, 2000.
[GVL] K. Fujimura and M. Terada, "XML Voucher: Generic Voucher [GVL] K. Fujimura and M. Terada, "XML Voucher: Generic Voucher
Language", draft-ietf-trade-voucher-lang-01.txt, 2001. Language", draft-ietf-trade-voucher-lang-02.txt, 2001.
[GVT] K. Fujimura, "Requirements for Generic Voucher Trading", [VTS] K. Fujimura, "Requirements and Design for Voucher Trading
draft-ietf-trade-drt-requirements-02.txt, 2001. System (VTS)", draft-ietf-trade-drt-requirements-03.txt, 2002.
[IOTP] D. Burdett, "Internet Open Trading Protocol - IOTP Version [IOTP] D. Burdett, "Internet Open Trading Protocol - IOTP Version
1.0", RFC 2801, 2000. 1.0", RFC 2801, 2000.
[JCC] Sun Microsystems Inc., "Java Commerce Client", [JCC] Sun Microsystems Inc., "Java Commerce Client",
<http://java.sun.com/products/commerce/>. <http://java.sun.com/products/commerce/>.
[RFC2119] S. Bradner, "Key words for use in RFCs to Indicate [RFC2119] S. Bradner, "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, 1997. Requirement Levels", BCP 14, RFC 2119, 1997.
 End of changes. 

This html diff was produced by rfcdiff 1.25, available from http://www.levkowetz.com/ietf/tools/rfcdiff/