Software Architecture Documentation (SAD)

Page tree


Contents

Interface identity

Resources

Data types and constants

Error handling

Variability

Quality attribute characteristics

Rationale and design issues

Usage guide

Interface identity

This is a SOAP web service interface named OpcOrderTrackingService. The main purpose of this web service is to track the status of a purchase order with a given order id.

Resources

OrderDetails getOrderDetails(String orderId)

Pre-conditions

  • The orderID argument must not be null.
  • The orderID must be a valid order id.

Post-conditions

  • Return the details of the purchase order, which include the status of each of the airline requests (both departing and returning flights), hotel booking request and activity requests.

Usage restrictions

  • Authorization. Only a signed in user is authorized to call this operation. A customer user can only get information about orders he created. A sales representative user can get information about any order.
  • 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.

Data types and constants

  • Type OrderDetails. This data structure contains the retrieved PurchaseOrder along with its status. Attributes:
PurchaseOrder PO
String status

The PurchaseOrder type is described in the OpcPurchaseOrderService interface documentation.

Error handling

The exceptions raised by this interface are:

  • OrderNotFoundException. The service throws this exception if no purchase order with the given order id was found, or the orderId was null or ill-formed.
  • 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

Rationale and design issues

Java-to-WSDL approach for design of interface

Since both the consumer website and the order processing center reside in the same enterprise we prefer the ease of development provided by JavaToWsdl compiler over stability of a manually-maintained WSDL description. However, this may result in rewriting the clients of this service every time we make a change to this interface.

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();
OpcOrderTrackingService opcOrderTrackingSvc =
     (OpcOrderTrackingService) ic.lookup("java:comp/env/service/OpcOrderTrackingService");
OrderTrackingIntf port = (OrderTrackingIntf) opcOrderTrackingSvc.getOrderTrackingIntfPort();
OrderDetails orderDetails = port.getOrderDetails(orderId);
  • No labels