OpcPurchaseOrderService Interface Documentation

From SAD

Jump to: navigation, search


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.


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.

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

  • The orderId argument is not null and corresponds to an existing purchase order.
  • 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.



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);
Personal tools