37.3. Widget Vendor Example
37.3.1. Widget Ordering Interface
This section shows an example of substitution groups being used in Apache CXF to solve a real world application. A service and consumer are developed using the widget substitution group defined in Example 37.2, “Substitution Group with Complex Types”. The service offers two operations:
checkWidgets and placeWidgetOrder. Example 37.12, “Widget Ordering Interface” shows the interface for the ordering service.
Example 37.12. Widget Ordering Interface
<message name="widgetOrder">
<part name="widgetOrderForm" type="xsd1:widgetOrderInfo"/>
</message>
<message name="widgetOrderBill">
<part name="widgetOrderConformation"
type="xsd1:widgetOrderBillInfo"/>
</message>
<message name="widgetMessage">
<part name="widgetPart" element="xsd1:widget" />
</message>
<message name="numWidgets">
<part name="numInventory" type="xsd:int" />
</message>
<portType name="orderWidgets">
<operation name="placeWidgetOrder">
<input message="tns:widgetOrder" name="order"/>
<output message="tns:widgetOrderBill" name="bill"/>
</operation>
<operation name="checkWidgets">
<input message="tns:widgetMessage" name="request" />
<output message="tns:numWidgets" name="response" />
</operation>
</portType>
Example 37.13, “Widget Ordering SEI” shows the generated Java SEI for the interface.
Example 37.13. Widget Ordering SEI
@WebService(targetNamespace = "http://widgetVendor.com/widgetOrderForm", name = "orderWidgets")
@XmlSeeAlso({com.widgetvendor.types.widgettypes.ObjectFactory.class})
public interface OrderWidgets {
@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
@WebResult(name = "numInventory", targetNamespace = "", partName = "numInventory")
@WebMethod
public int checkWidgets(
@WebParam(partName = "widgetPart", name = "widget", targetNamespace = "http://widgetVendor.com/types/widgetTypes")
com.widgetvendor.types.widgettypes.WidgetType widgetPart
);
@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
@WebResult(name = "widgetOrderConformation", targetNamespace = "", partName = "widgetOrderConformation")
@WebMethod
public com.widgetvendor.types.widgettypes.WidgetOrderBillInfo placeWidgetOrder(
@WebParam(partName = "widgetOrderForm", name = "widgetOrderForm", targetNamespace = "")
com.widgetvendor.types.widgettypes.WidgetOrderInfo widgetOrderForm
) throws BadSize;
}Note
Because the example only demonstrates the use of substitution groups, some of the business logic is not shown.
37.3.2. The checkWidgets Operation
Overview
checkWidgets is a simple operation that has a parameter that is the head member of a substitution group. This operation demonstrates how to deal with individual parameters that are members of a substitution group. The consumer must ensure that the parameter is a valid member of the substitution group. The service must properly determine which member of the substitution group was sent in the request.
Consumer implementation
The generated method signature uses the Java class supporting the type of the substitution group's head element. Because the member elements of a substitution group are either of the same type as the head element or of a type derived from the head element's type, the Java classes generated to support the members of the substitution group inherit from the Java class generated to support the head element. Java's type hierarchy natively supports using subclasses in place of the parent class.
Because of how Apache CXF generates the types for a substitution group and Java's type hierarchy, the client can invoke
checkWidgets() without using any special code. When developing the logic to invoke checkWidgets() you can pass in an object of one of the classes generated to support the widget substitution group.
Example 37.14, “Consumer Invoking
checkWidgets()” shows a consumer invoking checkWidgets().
Example 37.14. Consumer Invoking checkWidgets()
System.out.println("What type of widgets do you want to order?");
System.out.println("1 - Normal");
System.out.println("2 - Wood");
System.out.println("3 - Plastic");
System.out.println("Selection [1-3]");
String selection = reader.readLine();
String trimmed = selection.trim();
char widgetType = trimmed.charAt(0);
switch (widgetType)
{
case '1':
{
WidgetType widget = new WidgetType();
...
break;
}
case '2':
{
WoodWidgetType widget = new WoodWidgetType();
...
break;
}
case '3':
{
PlasticWidgetType widget = new PlasticWidgetType();
...
break;
}
default :
System.out.println("Invaid Widget Selection!!");
}
proxy.checkWidgets(widgets);Service implementation
The service's implementation of
checkWidgets() gets a widget description as a WidgetType object, checks the inventory of widgets, and returns the number of widgets in stock. Because all of the classes used to implement the substitution group inherit from the same base class, you can implement checkWidgets() without using any JAXB specific APIs.
All of the classes generated to support the members of the substitution group for
widget extend the WidgetType class. Because of this fact, you can use instanceof to determine what type of widget was passed in and simply cast the widgetPart object into the more restrictive type if appropriate. Once you have the proper type of object, you can check the inventory of the right kind of widget.
Example 37.15, “Service Implementation of
checkWidgets()” shows a possible implementation.
Example 37.15. Service Implementation of checkWidgets()
public int checkWidgets(WidgetType widgetPart)
{
if (widgetPart instanceof WidgetType)
{
return checkWidgetInventory(widgetType);
}
else if (widgetPart instanceof WoodWidgetType)
{
WoodWidgetType widget = (WoodWidgetType)widgetPart;
return checkWoodWidgetInventory(widget);
}
else if (widgetPart instanceof PlasticWidgetType)
{
PlasticWidgetType widget = (PlasticWidgetType)widgetPart;
return checkPlasticWidgetInventory(widget);
}
}37.3.3. The placeWidgetOrder Operation
Overview
placeWidgetOrder uses two complex types containing the substitution group. This operation demonstrates to use such a structure in a Java implementation. Both the consumer and the service must get and set members of a substitution group.
Consumer implementation
To invoke
placeWidgetOrder() the consumer must construct a widget order containing one element of the widget substitution group. When adding the widget to the order, the consumer should use the object factory methods generated for each element of the substitution group. This ensures that the runtime and the service can correctly process the order. For example, if an order is being placed for a plastic widget, the ObjectFactory.createPlasticWidget() method is used to create the element before adding it to the order.
Example 37.16, “Setting a Substitution Group Member” shows consumer code for setting the widget property of the
WidgetOrderInfo object.
Example 37.16. Setting a Substitution Group Member
ObjectFactory of = new ObjectFactory();
WidgetOrderInfo order = new of.createWidgetOrderInfo();
...
System.out.println();
System.out.println("What color widgets do you want to order?");
String color = reader.readLine();
System.out.println();
System.out.println("What shape widgets do you want to order?");
String shape = reader.readLine();
System.out.println();
System.out.println("What type of widgets do you want to order?");
System.out.println("1 - Normal");
System.out.println("2 - Wood");
System.out.println("3 - Plastic");
System.out.println("Selection [1-3]");
String selection = reader.readLine();
String trimmed = selection.trim();
char widgetType = trimmed.charAt(0);
switch (widgetType)
{
case '1':
{
WidgetType widget = of.createWidgetType();
widget.setColor(color);
widget.setShape(shape);
JAXB<WidgetType> widgetElement = of.createWidget(widget);
order.setWidget(widgetElement);
break;
}
case '2':
{
WoodWidgetType woodWidget = of.createWoodWidgetType();
woodWidget.setColor(color);
woodWidget.setShape(shape);
System.out.println();
System.out.println("What type of wood are your widgets?");
String wood = reader.readLine();
woodWidget.setWoodType(wood);
JAXB<WoodWidgetType> widgetElement = of.createWoodWidget(woodWidget);
order.setWoodWidget(widgetElement);
break;
}
case '3':
{
PlasticWidgetType plasticWidget = of.createPlasticWidgetType();
plasticWidget.setColor(color);
plasticWidget.setShape(shape);
System.out.println();
System.out.println("What type of mold to use for your
widgets?");
String mold = reader.readLine();
plasticWidget.setMoldProcess(mold);
JAXB<WidgetType> widgetElement = of.createPlasticWidget(plasticWidget);
order.setPlasticWidget(widgetElement);
break;
}
default :
System.out.println("Invaid Widget Selection!!");
}Service implementation
The
placeWidgetOrder() method receives an order in the form of a WidgetOrderInfo object, processes the order, and returns a bill to the consumer in the form of a WidgetOrderBillInfo object. The orders can be for a plain widget, a plastic widget, or a wooden widget. The type of widget ordered is determined by what type of object is stored in widgetOrderForm object’s widget property. The widget property is a substitution group and can contain a widget element, a woodWidget element, or a plasticWidget element.
The implementation must determine which of the possible elements is stored in the order. This can be accomplished using the
JAXBElement<? extends T> object's getName() method to determine the element's QName. The QName can then be used to determine which element in the substitution group is in the order. Once the element included in the bill is known, you can extract its value into the proper type of object.
Example 37.17, “Implementation of
placeWidgetOrder()” shows a possible implementation.
Example 37.17. Implementation of placeWidgetOrder()
public com.widgetvendor.types.widgettypes.WidgetOrderBillInfo placeWidgetOrder(WidgetOrderInfo widgetOrderForm)
{
ObjectFactory of = new ObjectFactory(); 1
WidgetOrderBillInfo bill = new WidgetOrderBillInfo() 2
// Copy the shipping address and the number of widgets
// ordered from widgetOrderForm to bill
...
int numOrdered = widgetOrderForm.getAmount(); 3
String elementName = widgetOrderForm.getWidget().getName().getLocalPart(); 4
if (elementName.equals("woodWidget") 5
{
WoodWidgetType widget=order.getWidget().getValue(); 6
buildWoodWidget(widget, numOrdered);
// Add the widget info to bill
JAXBElement<WoodWidgetType> widgetElement = of.createWoodWidget(widget); 7
bill.setWidget(widgetElement); 8
float amtDue = numOrdered * 0.75;
bill.setAmountDue(amtDue); 9
}
else if (elementName.equals("plasticWidget")
{
PlasticWidgetType widget=order.getWidget().getValue();
buildPlasticWidget(widget, numOrdered);
// Add the widget info to bill
JAXBElement<PlasticWidgetType> widgetElement = of.createPlasticWidget(widget);
bill.setWidget(widgetElement);
float amtDue = numOrdered * 0.90;
bill.setAmountDue(amtDue);
}
else
{
WidgetType widget=order.getWidget().getValue();
buildWidget(widget, numOrdered);
// Add the widget info to bill
JAXBElement<WidgetType> widgetElement = of.createWidget(widget);
bill.setWidget(widgetElement);
float amtDue = numOrdered * 0.30;
bill.setAmountDue(amtDue);
}
return(bill);
}
The code in Example 37.17, “Implementation of
placeWidgetOrder()” does the following:
- 1
- Instantiates an object factory to create elements.
- 2
- Instantiates a
WidgetOrderBillInfoobject to hold the bill. - 3
- Gets the number of widgets ordered.
- 4
- Gets the local name of the element stored in the order.
- 5
- Checks to see if the element is a
woodWidgetelement. - 6
- Extracts the value of the element from the order to the proper type of object.
- 7
- Creates a
JAXBElement<T>object placed into the bill. - 8
- Sets the bill object's widget property.
- 9
- Sets the bill object's amountDue property.
