Software Architecture Documentation (SAD)

Page tree


The identity of the interface

The name of this web service is OpcPurchaseOrderService.

Resources provided

  1. Resource Syntax
    public String submitPurchaseOrder(PurchaseOrder poObject) throws InvalidPOException, ProcessingException, RemoteException;
  2. Resource semantics
    1. Pre-conditions
      1. The PurchaseOrder argument must not be null.
      2. 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
    2. Post-conditions
      1. A successful call to this interface will result in the return of a unique purchase order id.
  3. Resource usage restrictions
    1. Concurrent access. There does not exist any limitation on the number of concurrent accesses of this interface. It is implemented using Enterprise Java Beans and concurrent accesses to it are managed by the EJB container. The interface by itself does not validate the values of the components of the PurchaseOrder argument. It only checks if they are null or not. If there is some unforseen error during the processing of the purchase order after this interface has returned to the caller, the error is handled elsewhere and is not the responsibility of this interface.

Locally defined data types

  • Type PurchaseOrder. This type is used as an argument to the service call. Basically it is a data structure that holds all the necessary information to place an order. It is made up of a number of components, each of which are described below.
name="poId" type="string" 
name="userId" type="string"
name="emailId" type="string" 
name="orderDate" type="dateTime" 
name="startDate" type="dateTime" 
name="activities" type="Activity" minOccurs="0" maxOccurs="unbounded"
name="billingInfo" type="ContactInfo" 
name="shippingInfo" type="ContactInfo" 
name="creditCard" type="CreditCard" 
name="departureCity" type="string" 
name="departureFlightInfo" type="Transportation" 
name="returnFlightInfo" type="Transportation" 
name="lodging" type="Lodging" 
name="endDate" type="dateTime" 
name="headCount" type="int"
name="locale" type="string" 
name="totalPrice" type="float"
  • Type Activity. This type is used to describe each activity that the user chooses as part of the purchase order.
name="activityId" type="string" 
name="endDate" type="dateTime" 
name="headCount" type="int"
name="location" type="string" 
name="name" type="string" 
name="price" type="float"
name="startDate" type="dateTime"
  • Type ContactInfo. This type is used to store the contact information of the user.
name="address" type="Address" 
name="email" type="string" 
name="familyName" type="string" 
name="givenName" type="string" 
name="phone" type="string"
  • Type Address. This type is used to store the address of the user.
name="city" type="string" 
name="country" type="string" 
name="postalCode" type="string" 
name="state" type="string" 
name="streetName1" type="string" 
name="streetName2" type="string"
  • Type CreditCard. This type is used to store the credit card information of the user.
name="cardExpiryDate" type="string" 
name="cardNumber" type="string" 
name="cardType" type="string"
  • Type Transporation. This type is used to store the airline information, and other transport related information of the purchase order.
name="carrier" type="string" 
name="departureDate" type="dateTime" 
name="departureTime" type="string" 
name="destination" type="string" 
name="headCount" type="int"
name="origin" type="string" 
name="price" type="float"
name="transportationId" type="string" 
name="travelClass" type="string"
  • Type Lodging. This type is used to store the lodging related information of the purchase order.
name="endDate" type="dateTime" 
name="location" type="string" 
name="lodgingId" type="string" 
name="name" type="string" 
name="noNights" type="int"
name="noRooms" type="int"
name="pricePerNight" type="float"
name="startDate" type="dateTime"

Error handling

The exceptions raised by this interface are:

  1. InvalidPOException. The service throws this exception if the purchase order is null, or if any of the components that make up the purchase order are null.
  2. 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.
  3. RemoteException. A RemoteException is thrown when there is an error in connection.

Any variability provided by the interface

None.

Quality attribute characteristics of the interface

  1. Scalability. This interface is internally implemented using Enterprise Java Beans and therefore it is scalable (allows scaling of number of requests it can handle). Also, this service is asynchronous in nature, which means the client can continue after making a call to it.
  2. Security. Security is important since credit card information is part of the PurchaseOrder argument. We choose https for our security requirements because that increases inter-operability (TODO: Not sure if this is a good enough reason, although we did use web services to increase inter-operability. So, in that sense it is a valid reason).

What the element requires

TODO: What the element requires may be specific, named resources provided by other elements. The documentation obligation is the same as for resources provided: syntax, semantics, and any usage restrictions.

Rationale and design issues

Java-WSDL approach for design of interface

We chose the Java-WSDL approach for design of this interface because we don't care much for the stability of the web service. This is because both the consumer website and the order processing center reside in the same enterprise.

Using the EJB endpoint type

We chose the EJB endpoint type because the order processing center is implemented using a set of session beans.

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 these services individually and hence have no reason to provide fine-grained versions of the web services.

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. The return type is a simple String that is the purchase order's unique id.

Publishing the web service as a WSDL

This web service is published as a WSDL in a well known location since it is not available for general public use. It is only used by the consumer website.

Usage guide

None.

  • No labels