Contents
Quality attribute characteristics
Interface identity
The is a SOAP web service interface named OpcPurchaseOrderService. The main purpose of this web service is to allow clients to place a purchase order.
Resources
String submitPurchaseOrder(PurchaseOrder poObject)Submit a complete purchase order for an adventure package. This operation returns the order ID as a String. The operation simply checks if the PurchaseOrder argument is valid. If it is valid, the order is created in the database and this operation returns to the caller. The actual processing of the purchase order is carried on in background. If there is some unforeseen error during the processing of the purchase order after this operation has returned to the caller, the error is handled elsewhere and is not the responsibility of this interface.
Pre-conditions
- The PurchaseOrder argument must not be null.
- The following components of the PurchaseOrder argument must not be null: user-id, email-id, locale, order date, shipping information, billing information, total price, credit card information, head count information, start date, end date and departure city
Post-conditions
- A successful call to this interface will return a unique purchase order id.
Usage restrictions
- Authorization. Can only be called by signed in users.
- Concurrent access. There isn't any limitation on the number of concurrent accesses of this interface. The service is implemented by using EJBs and concurrent calls to it are managed by the EJB container.
Error handling
- InvalidPOException. The service throws this exception if the purchase order is null, or if any of the components that make up the purchase order is null.
- ProcessingException. If the processing of the purchase order fails after it has passed its validation (i.e., there is no InvalidPOException), then a ProcessingException is thrown. This indicates that the purchase order is valid but something has gone wrong while placing the order.
boolean cancelPurchaseOrder(String orderId)Cancel the given purchase order. The operation returns true if the order was canceled successfully; it returns false when the purchase order processing is in a state where some bookings are already confirmed and cannot be canceled.
Pre-conditions
- The orderId argument is not null and corresponds to an existing purchase order.
Post-conditions
- If the operation returns true, the order is canceled and all reservations corresponding to this order are canceled. Charges to the customer credit card, if any were made, are also canceled.
- If the operation returns false, the state of the order remains unchanged.
Usage restrictions
- Authorization. This operation can only be called by a signed in user. A customer user can only cancel purchase orders he created. A sales representative user can cancel any order.
Error handling
- InvalidPOException. The service throws this exception if the order ID is null or the corresponding order doesn't exist.
- ProcessingException. Thrown if the order exists but is already canceled.
Data types and constants
- Type PurchaseOrder. This type is used as an argument to the submitPurchaseOrder operation. It is a data structure that contains all the necessary information to place an order. The attributes of a PurchaseOrder object are listed below.
String poId
String userId
String emailId
DateTime orderDate
DateTime startDate
Activity[] activities
ContactInfo billingInfo
ContactInfo shippingInfo
CreditCard creditCard
String departureCity
Transportation departureFlightInfo
Transportation returnFlightInfo
Lodging lodging
DateTime endDate
int headCount
String locale
float totalPrice- Type Activity. This type is used to describe each activity that the user chooses as part of the purchase order.
String activityId
DateTime endDate
int headCount
String location
String name
float price
DateTime startDate - Type ContactInfo. This type is used to store the contact information of the user.
Address address
String email
String familyName
String givenName
String phone - Type Address. This type is used to store the address of the user.
String city
String country
String postalCode
String state
String streetName1
String streetName2 - Type CreditCard. This type is used to store the credit card information of the user.
String cardExpiryDate
String cardNumber
String cardType - Type Transporation. This type is used to store the airline information, and other transport related information of the purchase order.
String carrier
DateTime departureDate
String departureTime
String destination
int headCount
String origin
float price
String transportationId
String travelClass - Type Lodging. This type is used to store the lodging information of the purchase order.
DateTime endDate
String location
String lodgingId
String name
int noNights
int noRooms
float pricePerNight
DateTime startDate Error handling
All operations in this interface can raise the following exception, in addition to operation specific exceptions:
- RemoteException. The caller receives a RemoteException when there is a communication problem with the service provider implementing this interface.
Variability
N/A
Quality attribute characteristics
- Scalability: see discussion in Deployment View - Rationale.
- Modifiability: this is an asynchronous service that results in loose coupling between the consumer website and the order processing center. Moreover, the SOAP interface defined in WSDL can be versioned and more than one version can be supported.
Rationale and design issues
Coarse-grained granularity of service
Currently we only expose placing a purchase order as a single web service that includes placing orders for activities, transportation and lodging. We don't provide separate operations to place an order only for flights, lodging or activities. Therefore, this interface is less flexible in terms of composing different kinds of orders. On the other hand, submitting a complete purchase order involves a single call.
Using JAX-RPC for passing parameters
Since the consumer website and the order processing center reside in the same enterprise, we avoid using complex XML processing and pass parameters as Java objects. It makes the interface slightly less interoperable but simplifies implementation.
Publishing the web service as a WSDL
This web service is published as a WSDL in a well known location (static web service instead of using a registry) since it is not available for general public use. It is only used by the consumer website. The option to use SOAP instead of Java RMI or direct EJB calls is motivated by the possibility of replacing the Consumer website implementation with a different technology (e.g., .NET); SOAP can provide the required interoperability in that case.
Using the EJB endpoint type
We chose the EJB endpoint type because the order processing center is implemented using a set of session beans.
Usage guide
Context ic = new InitialContext();
Service opcPurchaseOrderSvc = (Service) ic.lookup("java:comp/env/service/OpcPurchaseOrderService");
PurchaseOrderIntf port = (PurchaseOrderIntf) opcPurchaseOrderSvc.getPort(PurchaseOrderIntf.class);
String orderId = port.submitPurchaseOrder(myPurchaseOrder);