JavaBeat » XML & Web Services

Generate XSD from XML files

krishnas — Thu, 12 Apr 2012 06:09:26 +0000

XSD is the XML schema definition for defining the XML elements in the XML document. Prior to the XML schemas, DTDs are used which are not XML document and has the limitations. XSD is most popular because of the extensibility and the validations for the XML files. You can set the validation rules for the XML files and the values in the XML documents can be validated using the XSD documents. There are number of tools available in the internet to perform the validation tasks.

There are times when developer wants to generate the XSD from the XML files. In a typical scenario, XSD is written seperately without referring the XML document because XML data can be wrong. In case, if you don’t have the XSD for an XML document and want to generate the XSD for that XML document, there are tools in the internet. This article is not to explain much detail on how to generate the XSD from XML, but to give an idea on where to get the details on the tools and guiding for the resources on the internet.

If you are facing any issues on converting the XML files into the XSD, please post it here.

Java ME and Web services

krishnas — Thu, 31 Mar 2011 13:45:14 +0000

Connect to us ( @twitter | @facebook )

Introduction

Java Micro Edition (Java ME) is a platform for running applications on smaller devices such as mobile phones, PDAs etc. These devices have restrictions in terms of Memory and Processing power. Java ME defines various configurations and profiles. Midlets are java applications that operate on Mobile Information Device Profile (MIDP) which is targeted on Mobile phones that has limited memory and processing power. If you are new to Java ME please refer to the articles Introduction to J2ME and J2ME User Interface in Java Beat.

Due to the limitations on the mobile phones, the midlets can’t be exposed as a web service. But the midlets can consume web services. Java ME provides a subset of JAX-RPC APIs to work with web services. This article will provide a step by step procedure to access web services from a midlet.

Invoking web services from a Midlet

To access web services, the Midlet has to make remote calls on the web services. But the Midlets won’t do this directly. A stub has to be created and calls are made via the stub instance. Using wireless toolkit it is made very simple to create stub code. Invocation on web service method is a synchrous process. The parameters for the methods are passes by value instead of pass by references. Similarly the values are returned by web services as pass by value. On the stubs midlets can set some properties like USERNAME_PROPERTY, PASSWORD_PROPERTY (User name and password for authentication), ENDPOINT_ADDRESS_PROPERTY(Address of the endpoint) and SESSION_MAINTAIN_PROPERTY(if true:session will be maintained between endpoint and midlet) using _setProperty method.

1 2	stub._setProperty(Stub.ENDPOINT_ADDRESS_PROPERTY,serviceUrl); stub._setProperty(Stub.SESSION_MAINTAIN_PROPERTY, new Boolean(true));

The generated stub code and the supportive classes have to be bundled in the jar file along with the midlet. While accessing web services the best practice is to write the sub invocation code in a seperate thread. This will avoid your application hanging as your thread will be blocked during web service invocation.

Example

This example will help you in understanding how to access web service from a midlet. Netbeans IDE, Glassfish application server and Wireless tool kit 2.5.2 are used.

Create the web service and deploy it in the application server

Web service:

package mypack;
	import javax.jws.WebMethod;
	import javax.jws.WebParam;
	import javax.jws.WebService;
	@WebService()
	public class HelloService {
		@WebMethod(operationName = "getMessage")
		public String getMessage(@WebParam(name = "name")
		String name) {
			return "Hi "+name+"! Welcome to JME Programming";
		}
	}

WSDL URL:

http://localhost:17754/HelloWebService/HelloServiceService?WSDL

Create a Midlet with a form with a text field and command buttons.

public class Midlet extends MIDlet implements CommandListener{
		private Form myform;
		private TextField field;
		private Command exit,getMessage;
		private Display d;
		public void startApp() {
			d=Display.getDisplay(this);
			myform=new Form("Access Webservice");
			field=new TextField("Name", "", 20, TextField.PLAIN);
			exit=new Command("Exit", Command.EXIT, 0);
			getMessage=new Command("GetMsg", Command.SCREEN, 1);
			myform.append(field);
			myform.addCommand(exit);
			myform.addCommand(getMessage);
			myform.setCommandListener(this);
			d.setCurrent(myform);
		}
		public void pauseApp() {
		}
		public void destroyApp(boolean unconditional) {
		}
		public void commandAction(Command c, Displayable d) {
			if(c==exit){
				notifyDestroyed();
			}else if(c==getMessage){
				//Code to Access Webservice
			}
		}
	}

Use Wireless tool kit tool to create the stub

a) Open Wireless Toolkit

(b) Select File -> Utilities

d) Provide WSDL URL and the Output folder(src folder in Netbeans project) and the package details. Click on Ok

(e) The Stub and the other classes are generated in the src folder

Access Web service

For accessing web service,

Create a new thread.
In the new thread, Instantiate the stub
Set properties on the stub if required
Invoke the web service methods on the stub

//Extend the code written earlier
	import mypack.HelloService_Stub;
	public class Midlet extends MIDlet implements CommandListener{
		private Form myform;
		private TextField field;
		private Command exit,getMessage;
		private Display d;
		public TextField getField() {
			return field;
		}
		public Form getMyform() {
			return myform;
		}
		....
		public void commandAction(Command c, Displayable d) {
			if(c==exit){
				notifyDestroyed();
			}else if(c==getMessage){
				Thread t=new Thread(new NewThread(this));
				t.start();
			}
		}
	}	
	class NewThread implements Runnable{
		Midlet m;
		NewThread(Midlet m){
			this.m=m;
		}
		public void run() {
			Form frm=m.getMyform();
			TextField txt=m.getField();
			HelloService_Stub stub=new HelloService_Stub();
			String msg="";
			try {
				msg = stub.getMessage(txt.getString());
				frm.append(msg);
			} catch (RemoteException ex) {
				frm.append(ex.getMessage());
			}
		}
	}

Run the Midlet

Run the midlet. Provide the Name and select the command button GetMsg. The following output will be displayed.

Conclusion

Java ME Midlets can act only as the consumer for web services. It can’t be exposed as a web service. Wireless Tool Kit helps in creating stubs for web services. Midlets by invoking methods on the stub invokes methods on web services. Both simple types and complex types can be passed as parameters to the web services.

Apache Axis2 Web Services

krishnas — Fri, 11 Mar 2011 15:34:20 +0000

Connect to us ( @twitter | @facebook )

SOA, in practicality web services, is becoming the enabler for application integration. Since the introduction of web services, Apache Software Foundation has played a major role and produced several good web services frameworks. This book covers the defector Java Web Service framework, also known as Apache Axis2. This book covers several important facts that you would want to know about web services and writing, from simple web services to complex web services. By the end of this book, you will have learned about Axis2, its architectures and features, writing and deploying a simple service, writing service extensions and quality of services, POJO and JAX-WS services, clusters, and secure reliable web services.

What This Book Covers

Chapter 1, Apache Web Services and Axis2 – Gives you an introduction to web services and the web service stack at Apache.

Chapter 2, Looking inside Axis2 – Learn about Axis2 architecture and the importance of its components.

Chapter 3, Axis2 XML Model (AXIOM) – Learn about the heart of a web service framework and learning more about XML processing in Axis2.

Chapter 4, Execution Chain – Learn how to extend the core functionality of the
framework though handlers.

Chapter 5, Deployment Mode – Learn about the new and user friendly deployment model and several ways of deploying a service in Axis2.

Chapter 6, Information Model – Learn how Axis2 stores it static and dynamic data and the importance of it.

Chapter 7, Writing an Axis2 Service – Learn how to write a simple-complex service using Axis2 and how to deploy it

Chapter 8, Writing an Axis2 Module – Learn how to extend Axis2 core functionality
through a self-contained package.

Chapter 9, The Client API – Learn how to use Axis2 to invoke other services, available APIs, and how to use them.

Chapter 10, Session Management – Go beyond single invocation and learn how to use Axis2 features to provide better and more efficient statefull service.

Chapter 11, Developing JAX-WS Web Services – Learn the fundamentals of developing JAXWS based web services, the most popular web service development technology used by Java developers.

Chapter 12, Axis2 Clustering – Learn about clustering Apache Axis2, which will allow
you to deploy Axis2 in large scale production deployments.

Chapter 13, Enterprise Integration Patterns – Learn about some enterprise SOA deployment patterns that make use of the underlying Axis2 clustering infrastructure.

Chapter 14, Axis2 Advanced Features and Usage – Go beyond simple features and learn about REST, MTOM, and several other advanced features.

Chapter 15, Building a Secure Reliable Web Service – Learn how to use Axis2 and
related components to make your service more secure and reliableWriting an Axis2 Module Web services are gaining a lot of popularity in the industry and have become one of the major enabler for application integration. In addition, due to the fl exibility and advantages of using web services, everyone is trying to enable web service support for their applications. As a result, web service frameworks need to support new and more custom requirements. As we have already discussed in the previous chapters, one of the major goals of a web service framework is to deliver incoming messages into the target service. However, just delivering the message to the service is not enough; today’s applications are required to have reliability, security, transaction, and other quality services.

Due to the popularity of web services, standard bodies are producing new web service standards, and it is hard to support those new standards if the web service framework is not fl exible enough. From the very beginnings of Axis2, fl exibility and extensibility were the two main design considerations. The idea of Axis2 modules is to extend the core functionality of the system without performing any changes to the core system.
For example, Axis2 supports reliability and security as two separate modules, and the core engine is fully independent of those two qualities of service modules.

In this chapter, we will discuss the power of Axis2 modules and how to use them to
extend Axis2 to support for your own requirements. In particular, we will discuss
the following items:

Brief history of the Axis2 module
Introducing module concept
Structure of the module
Module configuration file (module.xml)
Optional module implementation class
Steps to writing a module.xml file
Deploying and engaging a module
Brief overview of the WS-Policy and its usage in modules

In our approach, we will be using code sample to help us understand the concepts better.

Brief history of the Axis2 module

Looking back at the history of Apache Web Services, the Handler concept can be considered as one of the most useful and interesting ideas. Due to the importance and fl exibility of the handler concept, Axis2 has also introduced it into its architecture. Notably, there are some major differences in the way you deploy handlers in Axis1 and Axis2. In Axis1, adding a handler requires you to perform global configuration changes and for an end user, this process may become a little complex. In contrast, Axis2 provides an easy way to deploy handlers. Moreover, in Axis2, deploying a handler is similar to deploying a service and does not require global configuration changes.

At the design stage of Axis2, one of the key considerations was to have a mechanism
to extend the core functionality without doing much. One of the main reasons behind the design decision was due to the lesson learned from supporting WS reliable messaging in Axis1. The process of supporting reliable messaging in Axis1 involved a considerable amount of work, and part of the reason behind the complex process was due to the limited extensibility of Axis1 architecture. Therefore, learning from a session in Axis1, Axis2 introduced a very convenient and fl exible way of extending the core functionality and providing the quality of services. This particular mechanism is known as the module concept.

Module concept

In Chapter 4, Execution Chain, we introduced and discussed the handler concepts and how to use handlers. As we discussed there, one of the main ideas behind a handler is to intercept the message fl ow and execute specific logic. In Axis2, the concept of a module is to provide a very convenient way of deploying service extension. We can also consider a module as a collection of handlers and required resources to run the handlers (for example, third-party libraries). One can also consider a module as an implementation of a web service standard specification. As an illustration, Apache Sandesha is an implementation of WS-RM specification. Apache Rampart is an implementation of WS-security; likewise, in a general module, is an implementation of a web service specification. One of the most important features and aspects of the Axis2 module is that it provides a very easy way to extend the core functionality and provide better customization of the framework to suit complex business requirements. A simple example would be to write a module to log all the incoming messages or to count the number of messages, if requested.

Module structure

As mentioned a few times before in previous chapters, Axis1 is one of the most
popular web service frameworks and it provides very good support for most of the
web service standards. However, when it comes to new and complex specifications,
there is a significant amount of work we need to do to achieve our goals. The problem becomes further complicated when the work we are going to do involves handlers, configuration, and third-party libraries. To overcome this issue, the Axis2 module concept and its structure can be considered as a good candidate. As we discussed in the deployment section, both Axis2 services and modules can be deployed as archive files. Inside any archive file, we can have configuration files, resources, and the other things that the module author would like to have.

It should be noted here that we have hot deployment and hot update
	support for the service; in other words, you can add a service when the
	system is up and running. However, unfortunately, we cannot deploy
	new modules when the system is running. You can still deploy modules,
	but Axis2 will not make the changes to the runtime system (we can drop
	them into the directory but Axis2 will not recognize that), so we will
	not use hot deployment or hot update. The main reason behind this is
	that unlike services, modules tend to change the system configurations,
	so performing system changes at the runtime to an enterprise-level
	application cannot be considered a good thing at all.

As we discussed earlier, adding a handler into Axis1 involves global configuration
changes and, obviously, system restart. In contrast, when it comes to Axis2, we can add handlers using modules without doing any global level changes. There are instances where you need to do global configuration changes, which is a very rare situation and you only need to do so if you are trying to add new phases and change the phase orders. You can change the handler chain at the runtime without downer-starting the system.

As mentioned earlier, changing the handler chain or any global
	configuration at the runtime cannot be considered a good habit. This is
	because in a production environment, changing runtime data may affect
	the whole system. However, at the deployment and testing time this
	comes in handy.

The structure of a module archive file is almost identical to that of a service archive
file, except for the name of the configuration file. We know that for a service archive
file to be a valid one, it is required to have a services.xml. In the same way, for a module to be a valid module archive, it has to have a module.xml file inside the META-INF directory of the archive. A typical module archive file will take the structure shown in the following screenshot. We will discuss each of the items in detail and create our own module in this chapter as well.

Module configuration file (module.xml)

As we have already discussed, the module archive file is a self-contained and
self-described file. In other words, it has to have all the configuration required to
be a valid and useful module. Needless to say, that is the beauty of a self-contained
package. The Module configuration file or module.xml file is the configuration file
that Axis2 can understand to do the necessary work.

A simple module.xml file has one or more handlers. In contrast, when it comes to
complex modules, we can have some other configurations (for example, WS policies,
phase rules) in a module.xml. First, let’s look at the available types of configurations
in a module.xml. For our analysis, we will use a module.xml of a module that counts
all the incoming and outgoing messages. We will be discussing all the important
items in detail and provide a brief description for the other items:

Handlers alone with phase rules
Parameters
Description about module
Module implementation class
WS-Policy
End points

Handlers and phase rules

As we discussed, a module is a collection of handlers, so a module could have one
or more handlers. Irrespective of the number of handlers in a module, module.
xml provides a convenient way to specify handlers. Most importantly, module.
xml can be used to provide enough configuration options to add a handler into the
system and specify the exact location where the module author would like to see the
handler running. In Chapter 4, Execution Chain, we learnt more about phase rules as
a mechanism to tell Axis2 to put handlers into a particular location in the execution
chain, so now it is time to look at them with an example.

Before learning how to write phase rules and specifying handlers in a module.xml,
let’s look at how to write a handler. There are two ways to write a handler in Axis2:

Implement the org.apache.axis2.engine.Handler interface
Extend the org.apache.axis2.handlers.AbstractHandler abstract class

In this chapter, we are going to write a simple application to provide a better
understanding of the module. Furthermore, to make the sample application easier,
we are going to ignore some of the difficulties of the Handler API. In our approach,
we will extend the AbstractHandler. When we extend the abstract class, we only
need to implement one method called invoke. So the following sample code will
illustrate how to implement the invoke method:

public class IncomingCounterHandler extends AbstractHandler implements
	CounterConstants {
		public InvocationResponse invoke(MessageContext messageContext) throws
		AxisFault {
			//get the counter property from the configuration context
			ConfigurationContext configurationContext = messageContext.
				getConfigurationContext();
			Integer count =
				(Integer) configurationContext.getProperty(INCOMING_
				MESSAGE_COUNT_KEY);
			//increment the counter
			count = Integer.valueOf(count.intValue() + 1 + «»);
			//set the new count back to the configuration context
			configurationContext.setProperty(INCOMING_MESSAGE_COUNT_KEY,
				count);
			//print it out
			System.out.println(«The incoming message count is now « +
				count);
			return InvocationResponse.CONTINUE;
		}
	}

As we can see, the method takes MessageContext as a method parameter and returns InvocationResponse as the response. You can implement the method as follows:

First get the configurationContext from the messageContext.
Get the property value specified by the property name.
Then increase the value by one.
Next set it back to configurationContext.
In general, inside the invoke method, as a module author, you have to do
all the logic processing, and depending on the result you get, we can decide
whether you let AxisEngine continue, suspend, or abort. Depending on your
decision, you can return to one of the three following allowed return types:

InvocationResponse.CONTINUEGive the signal to continue the message
InvocationResponse.SUSPENDThe message cannot continue as some of the conditions are not
satisfied yet, so you need to pause the execution and wait.
InvocationResponse.ABORTSomething has gone wrong, therefore you need to drop the message
and let the initiator know about it

The message cannot continue as some of the conditions are not satisfied yet,
so you need to pause the execution and wait.
InvocationResponse.ABORT.
Something has gone wrong, therefore you need to drop the message and let
the initiator know about it.

The corresponding CounterConstants class a just a collection of constants and will
look as follows:

public interface CounterConstants {
		String INCOMING_MESSAGE_COUNT_KEY = "incoming-message-count";
		String OUTGOING_MESSAGE_COUNT_KEY = "outgoing-message-count";
		String COUNT_FILE_NAME_PREFIX = "count_record";
	}

As we already mentioned, the sample module we are going to implement is for counting the number of request coming into the system and the number of messages
going out from the system. So far, we have only written the incoming message counter and we need to write the outgoing message counter as well, and the implementation of the out message count hander will look like the following:

public class OutgoingCounterHandler extends AbstractHandler implements
	CounterConstants {
		public InvocationResponse invoke(MessageContext messageContext)
		throws AxisFault {
			//get the counter property from the configuration context
			ConfigurationContext configurationContext = messageContext.
				getConfigurationContext();
			Integer count =
				(Integer) configurationContext.getProperty(OUTGOING_
				MESSAGE_COUNT_KEY);
			//increment the counter
			count = Integer.valueOf(count.intValue() + 1 + «»);
			//set it back to the configuration
			configurationContext.setProperty(OUTGOING_MESSAGE_COUNT_KEY,
				count);
			//print it out
			System.out.println(«The outgoing message count is now « +
				count);
			return InvocationResponse.CONTINUE;
		}
	}

The implementation logic will be exactly the same as the incoming handler processing, except for the property name used in two places.

Module implementation class

When we work with enterprise-level applications, it is obvious that we have to initialize various settings such as database connections, thread pools, reading property, and so on. Therefore, you should have a place to put that logic in your module. We know that handlers run only when a request comes into the system but not at the system initialization time. The module implementation class provides a way to achieve system initialization logic as well as system shutdown time processing. As we mentioned earlier, module implementation class is optional. A
very good example of a module that does not have a module implementation class is the Axis2 addressing module. However, to understand the concept clearly in our example application, we will implement a module implementation class, as shown below:

public class CounterModule implements Module, CounterConstants {
		private static final String COUNTS_COMMENT = "Counts";
		private static final String TIMESTAMP_FORMAT = "yyMMddHHmmss";
		private static final String FILE_SUFFIX = ".properties";
		public void init(ConfigurationContext configurationContext,
		AxisModule axisModule) throws AxisFault {
			//initialize our counters
			System.out.println("inside the init : module");
			initCounter(configurationContext, INCOMING_MESSAGE_COUNT_KEY);
			initCounter(configurationContext, OUTGOING_MESSAGE_COUNT_KEY);
		}
		private void initCounter(ConfigurationContext
			configurationContext,
			String key) {
			Integer count = (Integer) configurationContext.
				getProperty(key);
			if (count == null) {
				configurationContext.setProperty(key, Integer.
					valueOf("0"));
			}
		}
		public void engageNotify(AxisDescription axisDescription) throws
			AxisFault {
			System.out.println("inside the engageNotify " +
				axisDescription);
		}
		public boolean canSupportAssertion(Assertion assertion) {
			//returns whether policy assertions can be supported
			return false;
		}
		public void applyPolicy(Policy policy,
			AxisDescription axisDescription) throws
			AxisFault {
			// Configuure using the passed in policy!
		}
		public void shutdown(ConfigurationContext configurationContext)
			throws AxisFault {
			//do cleanup - in this case we'll write the values of the
			counters to a file
			try {
				SimpleDateFormat format = new SimpleDateFormat(TIMESTAMP_
					FORMAT);
				File countFile = new File(COUNT_FILE_NAME_PREFIX + format.
					format(new Date()) + FILE_SUFFIX);
				if (!countFile.exists()) {
					countFile.createNewFile();
				}
				Properties props = new Properties();
				props.setProperty(INCOMING_MESSAGE_COUNT_KEY,
					configurationContext.getProperty(INCOMING_MESSAGE_
					COUNT_KEY).toString());
				props.setProperty(OUTGOING_MESSAGE_COUNT_KEY,
					configurationContext.getProperty(OUTGOING_MESSAGE_
				COUNT_KEY).toString());
				//write to a file
				props.store(new FileOutputStream(countFile), COUNTS_
					COMMENT);
			} catch (IOException e) {
				//if we have exceptions we'll just print a message and let
				it go
				System.out.println("Saving counts failed! Error is " +
					e.getMessage());
			}
		}
	}

As we can see, there are a number of methods in the previous module implementation class. However, notably not all of them are in the module interface.
The module interface has only the following methods, but here we have some other
methods for supporting our counter module-related stuff:

init
engageNotify
applyPolicy
shutdown

At the system startup time, the init method will be called, and at that time, the module can perform various initialization tasks. In our sample module, we have initialized both in-counter and out-counter.

When we engage this particular module to the whole system, to a service, or to an
operation, the engagNotify method will be called. At that time, a module can decide whether the module can allow this engagement or not; say for an example, we try to engage the security module to a service, and at that time, the module finds out that there is a confl ict in the encryption algorithm. In this case, the module will not be able to engage and the module throws an exception and Axis2 will not engage the module. In this example, we will do nothing inside the engageNotify method.

As you might already know, WS-policy is one of the key standards and plays a major
role in the web service configuration. When you engage a particular module to a service, the module policy should be applied to the service and should be visible when we view the WSDL of that service. So the applyPolicy method sets the module policy to corresponding services or operations when we engage the module.
In this particular example, we do not have any policy associated with the module, so
we do not need to worry about this method as well.

As we discussed in the init method, the method shutdown will be called when the system has to shut down. So if we want to do any kind of processing at that time, we can add this logic into that particular method. In our example, for demonstration
purposes, we have added code to store the counter values in a file.

Webservices Articles & Books

Service-Oriented Architecture— An Integration Blueprint

krishnas — Fri, 15 Oct 2010 00:30:42 +0000

Connect to us ( @twitter | @facebook )

Service-Oriented Architecture— An Integration Blueprint

With the widespread use of service-oriented architecture (SOA), the integration of
different IT systems has gained a new relevance. The era of isolated business information
systems—so-called silos or stove-pipe architectures—is finally over. It is increasingly
rare to find applications developed for a specific purpose that do not need to exchange
information with other systems. Furthermore, SOA is becoming more and more widely
accepted as a standard architecture. Nearly all organizations and vendors are designing or
implementing applications with SOA capability. SOA represents an end-to-end approach
to the IT system landscape as the support function for business processes. Because of
SOA, functions provided by individual systems are now available in a single standardized
form throughout organizations, and even outside their corporate boundaries. In addition,
SOA is finally offering mechanisms that put the focus on existing systems, and make it
possible to continue to use them. Smart integration mechanisms are needed to allow
existing systems, as well as the functionality provided by individual applications, to be
brought together into a new fully functioning whole. For this reason, it is essential to
transform the abstract concept of integration into concrete, clearly structured, and
practical implementation variants.

The Trivadis Integration Architecture Blueprint indicates how integration architectures
can be implemented in practice. It achieves this by representing common integration
approaches, such as Enterprise Application Integration (EAI); Extract, Transform, and
Load (ETL); event-driven architecture (EDA); and others, in a clearly and simply
structured blueprint. It creates transparency in the confused world of product developers
and theoretical concepts.

The Trivadis Integration Architecture Blueprint shows how to structure, describe, and
understand existing application landscapes from the perspective of integration. The
process of developing new systems is significantly simplified by dividing the integration
architecture into process, mediation, collection and distribution, and communication
layers. The blueprint makes it possible to implement application systems correctly
without losing sight of the bigger picture: a high performance, flexible, scalable, and
affordable enterprise architecture.

What This Book Covers

Despite the wide variety of useful and comprehensive books and other publications on
the subject of integration, the approaches that they describe often lack practical relevance.
The basic issue involves, on the one hand, deciding how to divide an integration solution
into individual areas so that it meets the customer requirements, and on the other hand,
how it can be implemented with a reasonable amount of effort. In this case, this means
structuring it in such a way that standardized, tried-and-tested basic components can be
combined to form a functioning whole, with the help of tools and products. For this
reason, the Trivadis Integration Architecture Blueprint subdivides the integration layer
into further layers. This kind of layering is not common in technical literature, but it has
been proven to be very useful in practice. It allows any type of integration problem to be
represented, including traditional ETL (Extract, Transform, and Load), classic EAI
(Enterprise Application Integration), EDA (event-driven architecture), and grid
computing. This idea is reflected in the structure of the book.

Chapter 1, Basic Principles, covers the fundamental integration concepts. This chapter is
intended as an introduction for specialists who have not yet dealt with the subject of
integration.

Chapter 2, Base Technologies, describes a selection of base technologies. By far the most
important of these are transaction strategies and their implementation, as well as process
modeling. In addition, Java EE Connector Architecture (JCA), Java Business Integration
(JBI), Service Component Architecture (SCA), and Service Data Objects (SDO) are
explained. Many other base technologies are used in real-life integration projects, but
these go beyond the scope of this book.

Chapter 3, Integration Architecture Blueprint, describes the Trivadis Integration
Architecture Blueprint. The process of layering integration solutions is fully
substantiated, and each step is explained on the basis of the division of work between the
individual layers. After this, each of the layers and their components are described.

Chapter 4, Implementation Scenarios, demonstrates how the Trivadis Integration
Architecture Blueprint represents the fundamental integration concepts that have been
described in Chapter 1. We will use the blueprint with its notation and visualization to
understand some common integration scenarios in a mostly product-neutral form. We
will cover traditional, as well as modern, SOA-driven integration solutions.

Chapter 5, Vendor Products for Implementing the Trivadis Blueprint, completes the book
with a mapping of some vendor platforms to the Trivadis Integration Architecture
Blueprint.

Integration Architecture Blueprint

The Trivadis Integration Architecture Blueprint specifies the building blocks needed
for the effective implementation of integration solutions. It ensures consistent quality in
the implementation of integration strategies as a result of a simple, tried-and-tested
structure, and the use of familiar integration patterns (Hohpe, Wolf 2004).

Standards, components, and patterns used

The Trivadis Integration Architecture Blueprint uses common standardized techniques,
components, and patterns, and is based on the layered architecture principle.

A layered architecture divides the overall architecture into different layers with
different responsibilities. Depending on the size of the system and the problem involved,
each layer can be broken down into further layers. Layers represent a logical construct,
and can be distributed across one or more physical tiers. In contrast to levels, layers are
organized hierarchically, and different layers can be located on the same level. Within the
individual layers, the building blocks can be strongly cohesive. Extensive decoupling is
needed between the layers. The rule is that higher-level layers can only be dependent on
the layers beneath them and not vice versa. Each building block in a layer is only
dependent on building blocks in the same layer, or the layers beneath. It is essential to
create a layer structure that isolates the most important cohesive design aspects from one
another, so that the building blocks within the layers are decoupled.

The blueprint is process oriented, and its notation and structure are determined by the
blueprint’s dependencies and information flow in the integration process. An explanation
of how the individual layers, their building blocks, and tasks can be identified from the
requirements of the information flow is given on the basis of a simple scenario. In this
scenario, the information is transported from one source to another target system using an
integration solution.

In the blueprint, the building blocks and scenarios are described using familiar design
patterns from different sources:

(Hohpe, Wolf 2004)

(Adams et al. 2001)

(Coral8 2007)

(Russel et al. 2006)

These patterns are used in a shared context on different layers. The Trivadis Integration
Architecture Blueprint includes only the integration-related parts of the overall
architecture, and describes the specific view of the technical integration domain in an
overall architecture. It focuses on the information flow between systems in the context of
domain-driven design.

Domain-driven design is a means of communication, which is based on a profound
understanding of the relevant business domain. This is subsequently modeled specifically
for the application in question. Domain models contain no technical considerations and
are restricted exclusively to business aspects. Domain models represent an abstraction of
a business domain, which aims to capture the exemplary aspects of a specific
implementation for this domain. The objectives are:

To significantly simplify communication between domain experts and
developers by using a common language (the domain model)

To enable the requirements placed on the software to be defined more
accurately and in a more targeted way

It must be possible to describe, specify, and document the software more
precisely and more comprehensibly, using a clearly defined language, which
will make it easier to maintain

The technical aspects of architecture can be grouped into domains in order to create
specific views of the overall system. These domains cover security, performance, and
other areas. The integration of systems and information also represents a specific view of
the overall system, and can be turned into a domain.

Integration domain is used to mean different things in different contexts. One widelyused
meaning is “application domain”, in other words, a clearly defined, everyday
problem area where computer systems and software are used. Enterprise architectures are
often divided into business and technical domains:

Business domains may include training, resource management, purchasing,
sales or marketing, for example.

Technical domains are generally areas such as applications, integration,
network, security, platforms, systems, data, and information management.

The blueprint, however, sees integration as a technical domain, which supports business
domains, and has its own views that can be regarded as complementary to the views of
other architecture descriptions.

In accordance with Evans (Evans, 2004), the Trivadis Integration Architecture Blueprint
is a ubiquitous language for describing integration systems. This and the structure of the
integration domain on which it is based, have been tried and tested in a variety of
integration projects using different technologies and products. The blueprint has
demonstrated that it offers an easy-to-use method for structuring and documenting
implementation solutions. As domain models for integration can be formulated
differently depending on the target platform (for example, an object-oriented system or a
classic ETL solution), the domain model is not described in terms of object orientation.
Instead, the necessary functionality takes the form of building blocks (which are often
identical with familiar design patterns) on a higher level of abstraction. This makes it
possible to use the blueprint in a heterogeneous development environment with profitable
results.

An architecture blueprint is based on widely-used, tried-and-tested techniques,
components and patterns, which are grouped into a suitable structure to meet the
requirements of the target domain.

The concepts, the functionality, and the building blocks to be implemented are described
in an abstract form in blueprints. These are then replaced or fine-tuned by productspecific
building blocks in the implementation project. Therefore, the Trivadis Integration
Architecture Blueprint has been deliberately designed to be independent of individual
vendors, products, and technologies. It includes integration scenarios and proposals that
apply to specific problems, and can be used as aids during the project implementation
process. The standardized view of the integration domain and the standardized means of
representation enable strategies, concepts, solutions, and products to be compared with
one another more easily in evaluations of architectures.

The specifications of the blueprint act as guidelines. Differences between this model and
reality may well occur when the blueprint is implemented in a specific project. Individual
building blocks and the relationships between them may not be needed, or may be
grouped together. For example, the adapter and mapper building blocks may be joined
together to form one component in implementation processes or products.

Structuring the integration blueprint

The following diagram is an overview of the Trivadis Integration Architecture Blueprint.
It makes a distinction between the application and information view and the
integration view.

Insertt image 1049EN_03_01.png

The application and information view consists of external systems, which are to be
connected together by an integration solution. These are source or target entities in the
information flow of an integration solution. Generally one physical system can also take
on both roles. The building blocks belonging to the view, and the view itself, must be
regarded as external to the integration system that is being described and, therefore, not
the subject of the integration blueprint. The external systems can be divided into three
main categories:

Transactional information storage: This includes classic relational
database management systems (RDBMS) and messaging systems (queues,
topics). The focus is on data integration.

Non-transactional information storage: This primarily file-based systems
and non-relational data stores (NoSQL) with a focus on data integration.

Applications: Applications include transactional or non-transactional
systems that are being integrated (ERP—Enterprise Resource Planning,
CMS—Content Management System, and so on) and can be accessed
through a standardized API (web service, RMI/IIOP, DCOM, and so on).
The focus is on application and process integration.

The integration view lies at the heart of the integration blueprint and is divided (on the
basis of the principle of divide and conquer) into the following levels:

Transport level: The transport level encapsulates the technical details of
communication protocols and formats for the external systems. It contains:

Communication layer: The communication layer is part of the
transport level, and is responsible for transporting information.
This layer links the integration solution with external systems,
and represents a type of gateway to the infrastructure at an
architectural level. It consists of transport protocols and formats.

Integration domain level: The integration domain level covers the classic
areas of integration, including typical elements of the integration domain,
such as adapters, routers, and filters. It is divided into:

Collection/distribution layer: This layer is responsible for
connecting components. It is completely separate from the main
part of the integration domain (mediation). The building blocks
in this layer connect the mediation layer above with the
communication layer below. The layer is responsible for
encapsulating external protocols and their technical details from
the integration application, and transforming external technical
formats into familiar internal technical formats.

Mediation layer: This layer is responsible for forwarding
information. Its main task is to ensure the reliable forwarding of
information to business components in the process layer, or
directly to output channels that are assigned to the
collection/distribution layer, and that distribute data to the target
systems. This is the most important functionality of the
integration domain. In more complex scenarios, the information
forwarding process can be enhanced by information
transformation, filtering, and so on.

Application level: The application level encapsulates the integration
management and process logic. It is an optional level and contains:

Process layer: The process layer is part of the application level,
and is responsible for orchestrating component and service calls.
It manages the integration processes by controlling the building
blocks in the mediation layer (if they cannot act autonomously).

The integration view contains additional functionality that cannot be assigned to any of
the levels and layers referred to above. This functionality consists of so-called
cross-cutting concerns that can be used by building blocks from several other layers.
Cross-cutting concerns include:

Assembly/deployment: Contains configurations (often declarative or
scripted) of the components and services. For example, this is where the
versioning of Open Service Gateway initiative (OSGi) services is specified.

Transaction: Provides the transaction infrastructure used by the building
blocks in the integration domain.

Security/management: This is the security and management infrastructure
used by the building blocks in the integration domain. It includes, for
example, libraries with security functionality, JMX agents and similar
entities.

Monitoring, BAM, QoS: These components are used for monitoring
operations. This includes ensuring compliance with the defined Service
Level Agreements (SLA) and Quality of Service (QoS). Business Activity
Monitoring (BAM) products can be used for monitoring purposes.

Governance: These components and artifacts form the basis for SLAs and
QoS. The artifacts include business regulations, for example. In addition, this
is where responsibilities, functional and non-functional requirements, and
accounting rules for the services/capacities used are defined.

Developing a Web Service with CXF

krishnas — Fri, 23 Jul 2010 23:55:33 +0000

Connect to us ( @twitter | @facebook )

Apache CXF Web Service Development

Apache CXF is an open source services framework that makes web service development
easy, simplified, and standard based. CXF provides many features such as frontend
programming, support for different transports and data bindings, support for different
protocols, and other advanced concepts like Features and Invokers. It also provides a
programming model to build and deploy RESTful services.

The focus of the book is to provide readers with comprehensive details on how to use the
overview of CXF features and architecture. Each feature is explained in a separate
chapter, each of which covers well defined practical illustrations using real world
examples. This helps developers to easily understand the CXF API. Each chapter
provides hands on examples and provides step-by-step instructions to develop, deploy,
and execute the code.

What This Book Covers

The book is about the CXF service development framework. The book covers two of the
most widely used approaches, for web services development, SOAP and REST. Each
chapter in the book provides hands on examples, where we look in detail at how to use
the various CXF features in detail to develop web services in a step-by-step fashion

Chapter 1: Getting Familiar with CXF revisits web service concepts and provides an
introduction to CXF framework and its usage, and prepares the CXF environment for the
following chapters. By the end of this chapter the reader will be able to understand the
core concepts of CXF.

Chapter 2: Developing a Web Service with CXF focuses on getting the reader quickly
started with the CXF framework by developing a simple web service and running it under
the Tomcat container.

By the end of this chapter the reader will be able to develop a simple web service
using CXF.

Chapter 3: Working with CXF Frontends illustrates the use of different frontends, like
JAX-WS and CXF simple fronted API, and shows how to apply code-first and contractfirst
development approaches for developing web services. We will look at how to create
dynamic web service clients, the use of web service context, and how to work directly
with XML messages using CXF Provide and Dispatch implementation.

By the end of this chapter the reader will be able to apply different frontends to develop a
web service.

Chapter 4: Learning about Service Transports explains basic transport protocols for a
service and shows you how to configure HTTP, HTTP(s), JMS, and Local protocol for
web services communication. You will get introduced to the concept of HTTP conduit,
which enables the client program to apply policies or properties to HTTP and HTTPs
protocols, and how to generate a crypto key and a key store for HTTPs based service
communication. You will learn how to use JMS protocol for web services
communication and how to facilitate web services message exchange using CXF Local
service transport.

By the end of this chapter the reader will be able develop services with
different transports

Chapter 5: Implementing Advanced Features will explain advanced concepts using CXF
Features, Interceptors, and Invokers, and how to integrate these concepts in existing
applications.

By the end of this chapter the reader will be able develop services with features like
Interceptors and Invokers

Chapter 6: Developing RESTful Services with CXF explains the concept of REST
demonstrates additional features for developing enterprise RESTful services. We will
look at how to design, develop, and unit test the RESTful Service by taking a real world
example using CXF JAX-RS implementation.

By the end of this chapter the reader will be able to design, develop, and unit test the
RESTful service

Chapter 7: Deploying RESTful Services with CXF will explain how to deploy
REST services in a container like Tomcat using Spring configuration, and how to
test out the various operations exposed by the RESTFul application using CXF RESTful
client APiusing a web service development tool. We will look at how to enable
exception handling, JSON message support, and logging support for RESTful
applications using CXF framework.

By the end of this chapter the reader would be able utilize various CXF features for
developing RESTful services and how to leverage Spring configuration for deploying
RESTful service in the tomcat container.

Chapter 8: Working with CXF Tools will explain some of the commonly used CXF
tools that assist us in web services development. We will look at how to invoke a real
world .NET service over the internet using a Java client and JavaScript, create web
service implementation from WSDL files, generate WSDL files from web service
implementation, and validate the WSDL file for compliance.

By the end of this chapter the reader will be able to use different CXF tools to
develop a service.

Appendix A deals with how to set up the CXF environment, provides details on how the
source code for each chapter is organized, and shows how to run the source code
examples using the ANT tool and Maven Tool.

Appendix B provides an explanation of the basics of the Spring framework and IoC
concepts, along with an end-to-end example which utilizes Spring IoC concepts.

By the end of this Appendix chapter the reader will have a good understanding of Spring
capabilities used in the context of CXF web services development in this book.

Developing a Web Service with CXF

The first chapter provided an introduction to web services and CXF framework. We
looked at the features supported by the CXF framework and how to set up the CXF
environment. This chapter will focus on programming web service with CXF. CXF
provides a robust programming model that offers simple and convenient APIs for
web service development. The chapter will focus on illustrating a simple web service
development using CXF and Spring-based configurations. The chapter will also talk
about the architecture of CXF.

Before we examine CXF-based web service development, we will review the example
application that will be illustrated throughout the book. The example application
will be called Order Processing Application. The book will demonstrate the same
application to communicate different concepts and features of CXF so that the reader
can have a better understanding of CXF as a whole. This chapter will focus on the
following topics:

Overview of a sample Order Processing Application

CXF-based web service development with Spring

Insight into CXF architecture

The Order Processing Application

The objective of the Order Processing Application is to process a customer order.
The order process functionality will generate the customer order, thereby making
the order valid and approved. A typical scenario will be a customer making an
order request to buy a particular item. The purchase department will receive the
order request from the customer and prepare a formal purchase order. The purchase
order will hold the details of the customer, the name of the item to be purchased,
the quantity, and the price. Once the order is prepared, it will be sent to the
Order Processing department for the necessary approval. If the order is valid and
approved, then the department will generate the unique order ID and send it back to
the Purchase department. The Purchase department will communicate the order ID
back to the customer.

For simplicity, we will look at the following use cases:

Prepare an order

Process the order

The client application will prepare an order and send it to the server application
through a business method call. The server application will contain a web service
that will process the order and generate a unique order ID. The generation of the
unique order ID will signify order approval.



	In real world applications a unique order ID is always accompanied by

	the date the order was approved. However, in this example we chose to

	keep it simple by only generating order ID.

Developing a service

Let’s look specifically at how to create an Order Processing Web Service and then
register it as a Spring bean using a JAX-WS frontend.

In Chapter 3 you will learn about the JAX-WS frontend. The chapter will also cover a brief discussion on JAX-WS. The Sun-based JAX-WS specification can be found at the following URL: http://jcp.org/aboutJava/communityprocess/final/

jsr224/index.html

JAX-WS frontend offers two ways of developing a web service—Code-first and
Contract-first. We will use the Code-first approach, that is, we will first create a Java
class and convert this into a web service component. The first set of tasks will be to
create server-side components.



	In web service terminology, Code-first is termed as the Bottoms Up

	approach, and Contract-first is referred to as the Top Down approach.

To achieve this, we typically perform the following steps:

Create a Service Endpoint Interface (SEI) and define a business method
to be used with the web service.

Create the implementation class and annotate it as a web service.

Create beans.xml and define the service class as a Spring bean using a
JAX-WS frontend.

RESTful Java Web Services

krishnas — Tue, 08 Dec 2009 00:39:02 +0000

Connect to us ( @twitter | @facebook )

RESTful Java Web ServicesThis article is sample chapter for the book RESTful Java Web Services. If you’re already familiar with REST theory, but are new to RESTful Java web services, and want to use the Java technology stack together with Java RESTful frameworks to create robust web services, this is the book for you.

This book is a guide for developing RESTful web services using Java and the most popular RESTful Java frameworks available today. This book covers the theory of REST, practical coding examples for RESTful clients, a practical outline of the RESTful design, and a complete implementation of a non-trivial web service using the frameworks Jersey’s JAX-RS, Restlet’s Lightweight REST, JBoss’s JAX-RS RESTEasy, and Struts 2 with the REST plugin.

We cover each framework in detail so you can compare their strengths and weaknesses. This coverage will also provide you with enough knowledge to begin developing your own web services after the first reading. What’s more, all the source code is included for
you to study and modify. Finally, we discuss performance issues faced by web service developers and cover practical solutions for securing your web services.

What This Book Covers

Chapter 1, RESTful Architectures, introduces you to the REST software architectural style and discusses the constraints, main components, and abstractions that make a software system RESTful. It also elaborates on the details of HTTP requests and responses between clients and servers, and the use of RESTful web services in the context of Service-Oriented Architectures (SOA).

Chapter 2, Accessing RESTful Services—Part 1, teaches you to code four different RESTful Java clients that connect and consume RESTful web services, using the messaging API provided by Twitter.

Chapter 3, Accessing RESTful Services—Part 2, shows you how to develop a mashup application that uses RESTful web services that connect to Google, Yahoo!, Twitter, and TextWise’s SemanticHacker API. It also covers in detail what it takes to consume JSON
objects using JavaScript.

Chapter 4, RESTful Web Services Design, demonstrates how to design a micro-blogging web service (similar to Twitter), where users create accounts and then post entries. It also outlines a set of steps that can be used to design any software system that needs to be
deployed as a RESTful web service.

Chapter 5, Jersey: JAX-RS, implements the micro-blogging web service specified in Chapter 4 using Jersey, the reference implementation of Sun’s Java API for RESTful Web Services.

Chapter 6, The Restlet Framework, implements the micro-blogging web service specified in Chapter 4 using the Restlet framework, using two of its latest versions, 1.1 and 2.0.

Chapter 7, RESTEasy: JAX-RS, implements the micro-blogging web service specified in Chapter 4 using JBoss’s RESTEasy framework.

Chapter 8, Struts 2 and the REST Plugin, implements the micro-blogging web service specified in Chapter 4 using Struts 2 framework (version 2.1.6) together with the REST plugin. This chapter covers configuration of Struts 2 and the REST plugin, mapping of URIs to Struts 2 action classes, and handling of HTTP requests using the REST plugin.

Chapter 9, Restlet Clients and Servers, extends coverage of the Restlet framework. This chapter looks at the client connector library and the standalone server library.

Chapter 10, Security and Performance, explores how to secure web services using HTTP Basic Authentication, and covers the OAuth authentication protocol. This chapter also covers the topics of availability and scalability and how they relate to implementing high
performing web services.

RESTful Web Services Design

The RESTful development process follows traditional development paradigms. However, with RESTful web services, we need to analyze the resource requirements first, design the representation for our resources second, identify the URIs third, and, lastly, worry about implementation technologies.

Throughout this book we’ve talked about creating web services that are noun dependent as opposed to verb dependent. In this chapter we’ll look at what that means in terms of the design process. For this, we’ll design a blogging application, but we’ll leave the implementation for later chapters. Our sample application is a micro-blogging web service (similar to Twitter), where users create accounts and then post entries.

Finally, while designing our application, we’ll define a set of steps that can be applied to designing any software system that needs to be deployed as a RESTful web service.

Designing a RESTful web service

Designing RESTful web services is not different from designing traditional web applications. We still have business requirements, we still have users who want to do things with data, and we still have hardware constraints and software architectures to deal with. The main difference, however, is that we look at the requirements to tease out resources and forget about specific actions to be taken on these resources.

We can think of RESTful web service design as being similar to Object Oriented Design (OOD). In OOD, we try to identify objects from the data we want to represent together with the actions that an object can have. But the similarities end at the data structure definition, because with RESTful web services we already have specific calls that are part of the protocol itself.The underlying RESTful web service design principles can be summarized in the following four steps:

Requirements gathering—this step is similar to traditional software requirement gathering practices.
Resource identification—this step is similar to OOD where we identify objects, but we don’t worry about messaging between objects.
Resource representation definition—because we exchange representation between clients and servers, we should define what kind of representation we need to use. Typically, we use XML, but JSON has gained popularity. That’s not to say that we can’t use any other form of resource representation—on the contrary, we could use XHTML or any other form of binary representation, though we let the requirements guide our choices.
URI definition—with resources in place, we need to define the API, which consists of URIs for clients and servers to exchange resources’ representations.

This design process is not static. These are iterative steps that gravitate around resources. Let’s say that during the URI definition step we discover that one of the URI’s responses is not covered in one of the resources we have identified. Then we go back to define a suitable resource. In most cases, however, we find that the resources that we already have cover most of our needs, and we just have to combine existing resources into a meta-resource to take care of the new requirement.

Requirements of sample web service

The RESTful web service we design in this chapter is a social networking web application similar to Twitter.

Throughout this book, we follow an OOD process mixed with an agile philosophy for designing and coding our applications. This means that we create just enough documentation to be useful, but not so much that we spend an inordinate amount of time deciphering it during our implementation phase.

As with any application, we begin by listing the main business requirements, for which we have the following use cases (these are the main functions of our application):

A web user creates an account with a username and a password (creating an account means that the user is now registered).

Registered users post blog entries to their accounts. We limit messages to 140 characters.

Registered and non-registered users view all blog entries.

Registered and non-registered users view user profiles.

Registered users update their user profiles, for example, users update their password.

Registered and non-registered users search for terms in all blog entries.

However simple this example may be, social networking sites work on these same principles: users sign up for accounts to post personal updates or information. Our intention here, though, is not to fully replicate Twitter or to fully create a social networking application. What we are trying to outline is a set of requirements that will test our understanding of RESTful web services design and implementation.

	The core value of social networking sites lies in the ability to connect
	to multiple users who connect with us, and the value is derived from
	what the connections mean within the community, because of the
	tendency of users following people with similar interests. For example,
	the connections between users create targeted distribution networks.

The connections between users create random graphs in the graph theory sense, where nodes are users and edges are connections between users. This is what is referred to as the social graph.

Resource identification

Out of the use cases listed above, we now need to define the service’s resources. From reading the requirements we see that we need users and messages. Users appear in two ways: a single user and a list of users. Additionally, users have the ability to post blog entries in the form of messages of no more than 140 characters. This means that we need resources for a single message and a list of messages. In sum, we identify the following resources:

User
List of users
Message
List of messages

Representation definition

As we discussed in our introduction to RESTful web services, a representation is a temporal mapping of a resource at the time of a request. Furthermore, a representation is transmitted between clients and servers over HTTP. Because of HTTP’s fl exibility, any binary stream can be transferred. Nevertheless, we don’t recommend choosing just any type of binary representation that requires special code or libraries to consume. We recommend using primarily XML and JSON structures, remembering, of course, that the requirements of the problem we’re solving dictate what representation types we must provide.

A well-designed RESTful web service needs to provide multiple resource representations. We can’t assume that only web browsers will be accessing our public APIs or that only the one type of client we identified in our requirement gathering process will use our services.

What are the options available, then?

Again, arriving at the ideal representation format is a matter of the design process. We need to take into account what the service is doing and what clients will be using the resources for. The safest representation format is therefore XML. This is what web services are known for: transferring XML streams over web transport protocols. More important, most programming languages already have libraries available to parse XML streams.

Finally, we need to account for linkability of representations. Linkability of representation means that the web services provide for resource discoverability, such that resources link to other resources (what’s currently being referred to as HATEOS or Hypermedia As The Engine Of State transfer). For example, our URI for a list of users returns a structure of users with each element in the list having a direct URI to each element in the service (a link to a user).

XML representations

From our analysis, we identified two types of resources: users and messages. As part of the heuristics we outlined earlier, we need to define what our representation will look like. The following representations are the structures that we will have to implement when we actually code the web service.

Users

We first define a user representation as follows:

As part of a user resource, we store only a username and a password. The username is unique in the context of our system and is used to uniquely identify each user. The link element, which points back to the web service, is either assigned when the resource is created or a representation is built for transport (for our sample service, we let the backend create the link).

We now define a list of users as follows:

...

This XML structure declares a list of users stored in an XML element . We use ellipses or … to show that we can have more than one user in the list.

	We can see here the linkability concept at play: with a list of users
	we can drill down to individual users using the link element's value.

Messages

We first define a single blog entry or message as follows:

A message needs a message id, the body of the message (the content element), and the user who posted the message. Note that depending on what we are doing with the message, we don’t pass all the resource’s information back and forth. For example, when we are creating a message at the client layer, we don’t know what the value for messageID is. Therefore, we still need to pass the message structure to the service, but our web service will know that any messageID value needs to be ignored, because, in our case, it will be created by the storage layer.

Finally, we define a list of messages as follows:

...

This XML structure holds a collection of messages, and each message holds the user who posted the message.

	We use the XML representation type for input and output.
	Input in this case means that we send a resource representation
	to create and update the resources at the web service layer in the
	form of an XML object. Output means that a client requests an XML
	representation of a resource.

JSON representations

We use the same key names for our JSON representation, and we still have only two types of resources: users and messages. Again, these structures are our specification of what we need to return for each request.

Users

We define a user representation as follows:

	{"user":{"username":"john", "password":"password", "link":"/users/
	john"}}

And we define a list of users as follows (we use the … characters to show that there is more than one user in the array):

	{"users-result":{"count":"6", "users":[{"username":"john",
	"password":"password", "link":"/users/john"}, ...,{"username":"jane",
	"password":"password", "link":"/users/jane"}]}}

The array for all users as a JSON structure, looks as follows:

	"users":[{"username":"john", "password":"password", "link":"/users/
	john"}, ...,{"username":"jane", "password":"password", "link":"/users/
	jane"}]

Once the JSON response has been evaluated with the JavaScript eval() function, similar to what we did in Chapters 2 and 3, we can then access any of the values in the structure. For example, if we need the user name of the first element on the array, we use users-result.users[0].username.

Messages

We now define a message representation as follows:

	{"message":{"messageID":"some-id", "content":"some content",
	"link":"/messages/some-id", "user":{"user":{"username":"john",
	"password":"password", "link":"/users/john"}}}

And a list of messages as follows:

	{"messages-result":{"count":"6", "link":"/messages",
	"messages":[{"messageID":"some-id", "content":"some content",
	"link":"/messages/some-id", "user":{"username":"john",
	"password":"password", "link":"/users/john"}}, ...,{"messageID":"someid2",
	"content":"some content", "link":"/messages/some-id2",
	"user":{"username":"jane", "password":"password", "link":"/users/
	jane"}}]}}

Each message element in the array has a user structure embedded as follows:

	{"messageID":"some-id", "content":"some content",
	"user":{"username":"john", "password":"password", "link":"/users/
	john"}}

Once the JSON response has been evaluated with the JavaScript eval() function, we can then access the first element on the list with messages-result.messages[0]. content; if we want to get the user name of the user who posted the message, we access the value with messages-result.messages[0].user.username.

	Note that during implementation we'll use JSON representations only
	as response streams. This means that we won't use JSON structures to
	create or update resources at the web service layer. Although we could
	use XML and JSON to update resources at the service layer, we'll omit
	JSON for the sake of brevity.

URI definition

The next step involves the definition of URIs. This is a crucial step, as the URIs define our API and it’s likely that we want to make our web service public.

We strive to make our APIs logical, hierarchical, and as permanent as we can. We must emphasize these three tenets, as we may have many developers depending on the services we make available. Therefore, a good API is one that doesn’t change too often and is unambiguous to use. Furthermore, the idea of RESTful APIs is that we maintain URI uniqueness and reliability of service. (For a complete discussion about this topic, see http://www.w3.org/Provider/Style/URI.)

The first thing we need is a web address. In our case, we assume that we’re using our development machine running on http://localhost:8080/.

	It's important to distinguish between a web service and a web application:
	we use web services to implement web applications, and web services
	can be, and are recommended to be, independent of web applications.
	What's more, web applications are meant to be consumed by humans,
	as opposed to web services that are intended for machine consumption.

For example, a RESTful API could live under http://api. restfuljava.com/ and a web application using the API could ive under http://restfuljava.com/. Both the API and the web application should be running on independent hardware for performance reasons, but when we get to implement our sample service we run everything on the same server.

The nomenclature of RESTful URIs falls under the topic of URI templates and the following conventions are widely used. First, for items or identifiers that don’t change, we find the keyword to be part of the actual URI—for instance, we use users to be the URI for a list of all users. Second, we use keys or dynamic keywords to be enclosed in { and }. Applying these conventions, our URI list for users looks as follows:

http://localhost:8080/users—with the GET method, this URI returns a list of all users; with the POST method, we create a new user and the payload is a user’s XML representation; we don’t support the PUT method; finally, we don’t support the DELETE method for an entire list of users

http://localhost:8080/users/{username}—with the GET method, this URI returns a representation of a user with a unique identifier username; with the PUT method, it updates a user; and, with the DELETE method, it deletes a user.

And for messages, our URI list looks as follows:

http://localhost:8080/messages—with the GET method, this URI returns a list of all messages from all users; with the POST method, it creates a new message, with the message’s XML representation as the payload of the request

http://localhost:8080/messages/{messageID}—with the GET method, this URI returns a representation for a message with the unique identifier messageID; with the DELETE method, it deletes a message; and we don’t support the POST or PUT methods

http://localhost:8080/messages/users/{username}—with the GET method, this URI returns a list of all message for a user with identifier username; no POST, PUT, or DELETE methods are supported

	At the time of this writing, the URI Template specification is still under
	review. For more information, see http://tools.ietf.org/html/
	draft-gregorio-uritemplate-03.

Executing logic with RESTful URIs

A question arises when designing RESTful web services that has to do with executing code at the server level. Specifically, how do we execute logic if we limit our client/server interactions to only four CRUD-like calls (POST, GET, PUT, and DELETE)? For this we need to introduce URIs that execute logic on the server,remembering that responses must be in the form of resource representations. In other
words, we avoid any RPC style calls and concentrate on the resources only.

For our web service, we only offer the ability of searching for a term or a phrase in the blog entries. For example, any user can search for the term “programming” or” software development” using the following URI (note that the URI pattern is arbitrary and you can choose whatever makes sense for the service you are developing):

	http://localhost:8080/messages/search/{search_item}

This URI returns a list of messages that contain the word or words search_item—this is strictly a GET method call and no POST, PUT, or DELETE method is supported.

Using URIs to request representation types

A RESTful web service is one that adheres to all the constraints we outlined in Chapter 1, RESTful Architectures. However, we have encountered APIs that don’t strictly adhere to every constraint. For example, requesting representation types via URIs is something we saw with Twitter’s API. We requested three different types of representations with the URI ttp://twitter.com/statuses/public_timeline. {xml, json, rss}.

We said that this is not technically a RESTful web service request, because we don’t use the communication protocol—HTTP headers—to tell the service what kind of representation to get. Even though this is not a RESTful web service, it still works. Nevertheless, the API may be open to interpretation. For example, what does it mean to send an HTTP GET request to the URI http://twitter.com/statuses/
public_timeline.json with an HTTP Accept header value of application/xml? Do we get a JSON representation or an XML epresentation? A properly designed RESTful web service has to adhere to all REST constraints, and using the protocol to negotiate representations is part of being RESTful.

Creating a properly defined RESTful web service, however, ensures that there are no misunderstandings on how to use such services. For example, setting the HTTP method type to GET with an appropriate Accept header value makes it clear that we are requesting a resource of a specific type. In the end, you, as a developer or software architect, need to make a decision as to which style will benefit your users the most.

Using this representation request style is a design decision that facilitates—it can be argued—the writing of clients. For instance, the majority of public APIs are read only, so using a straight HTTP GET request with the type of representation embedded in the URI is easier than instantiating a full HTTP request and modifying the HTTP header Accept each time. Note that neither is hard to implement; however, with the former, we save a couple of lines of code at the client layer. Again, it’s a matter of choice.

	Our sample web service is a canonical application, thus we don't deviate
	from any of the constraints. This means that we use the HTTP protocol
	to request a preferred resource representation and not the URI style
	described in this section.

Summary

As we’ve seen, the RESTful design process is resource centric. In addition, we have no arbitrary actions executing on the data—we have HTTP method calls that exchange representations using clearly defined URIs. The steps to arrive at a web service that adheres to all REST constraints are similar to traditional web application design. So we can still use all our traditional requirement gathering techniques, but tweak the process to account for proper design of usable URIs and consumable representations.

Now that we have our social networking web service specification defined together with a set of RESTful design principles, the next step is implementation. We have four different REST frameworks in the menu, so in the next chapter we begin with Jersey, which is the reference implementation of the Java API for RESTful Web Services Specification, more commonly known as JAX-RS.

Building SOA-Based Composite Applications Using NetBeans IDE 6

krishnas — Thu, 08 Oct 2009 14:11:59 +0000

Connect to us ( @twitter | @facebook )

Building SOA-Based Composite Applications Using NetBeans IDE 6

Composite applications aid businesses by stitching together various
componented business capabilities. In the current enterprise scenario,
empowering business users to react quickly to the rapidly changing business
environment is the top most priority. With the advent of composite applications
the ‘reuse’ paradigm has moved from the technical aspect to the business
aspect. You no longer re-use a service but re-use a business process. Now,
enterprises can define their own behaviors optimized for their businesses through
metadata and flows. This business process composition has become
increasingly important for constructing business logic.

The ability of composite applications to share components between them nullifies
the distinction between actual applications. Business users should be able to
move between the activities they need to do without any actual awareness that
they are moving from one domain to another.

The composite application design enables your company to combine multiple
heterogeneous technologies into a single application, bringing key application
capability within reach of your business user. Enterprises creating richer
composite applications by leveraging existing interoperable components increase
the development organization’s ability to respond quickly and cost-effectively to
emerging business requirements. While there are many vendors offering various
graphical tools to create composite applications, this book will focus on
OpenESB and NetBeans IDE for designing and building composite applications.

This book introduces basic SOA concepts and shows how you can use
NetBeans and OpenESB tools to design and deploy a composite application.
After introducing the SOA concepts, you are introduced to various NetBeans
Editors and aids that you need to understand and work with to design a
composite application. The last part of the book deals with a full fl edged
incremental example on how you can build a complex composite application with
necessary screen shots accompanied by the source code available on the
website.

What This Book Covers

Chapter 1 introduces SOA and BPEL to the readers with simple examples and
gives an overview of the JBI components and runtime required to build
composite applications. This chapter also gives you an overview of the need for
SOA-based applications in companies by depicting an example of an imaginary
AirlinesAlliance system.

Chapter 2 shows you how you can quickly setup NetBeans IDE and other
runtime environments including OpenESB runtime and BPEL engine. There are
many software/tools mentioned in this chapter that you need to download and
configure to get started building composite applications using NetBeans.

Chapter 3 provides an overview of Java Business Integration (JBI) and the
Enterprise Service Bus (ESB). You will learn about JBI Service Engines and how
they are supported within the NetBeans IDE.

Chapter 4 introduces JBI Binding Components and how they provide protocol
independent communication between JBI components. You will also learn about
the support that the NetBeans IDE provides for Binding Components.

Chapter 5 introduces the NetBeans BPEL Designer that comes bundled with the
NetBeans IDE. You will also be introduced to the graphical tools/wizards and
palettes available for creating BPEL files.

Chapter 6 provides an overview of WSDL and how WSDL documents are
formed. You will learn about the use of WSDL in enterprise applications and the
WSDL editor within the NetBeans IDE.

Chapter 7 covers the XML schema designer and shows how it aids rapid
development and testing of XML schema documents.

Chapter 8 provides you an overview of the Intelligent Event Processor (IEP)
module and the IEP Service Engine that can be acquired from the OpenESB
software bundle. This chapter also shows the need for an event processing tool
through simple composite application examples.

Chapter 9 provides details of fault handling within a BPEL process and shows
how these can be managed within the NetBeans IDE by using graphical tools.

Chapter 10 shows you how you can build simple to complex composite
applications and BPEL processes using the NetBeans IDE. The examples in this
chapter are divided into several parts and the source code for all parts is
available in the code bundle.

Chapter 11 gives you the overall picture of the composite application and the
need for a composite application to deploy your BPEL processes. The composite
application support provided in NetBeans IDE comes with a visual editor for
adding and configuring WSDL ports and JBI modules.

Service Engines

In Chapter 1, we introduced the concept of SOA applications, and introduced
BPEL processes and JBI applications. To gain a greater understanding of these
concepts and to enable us to develop enterprise level SOA applications, we need to
understand JBI in further depth, and how JBI components can be linked together.
This chapter will introduce the JBI Service Engine and how it is supported within the
NetBeans Enterprise Pack.

In this chapter, we will discuss the following topics:

Need for Java Business Integration (JBI)
Enterprise Service Bus
Normalized Message Router
Introduction to Service Engines
NetBeans Support for Service Engines
BPEL Service Engine
Java EE Service Engine
SQL Service Engine
IEP Service Engine
XSLT Service Engine

Need for Java Business Integration (JBI)

To have a good understanding of Service Engines (a specific type of JBI component),
we need to first understand the reason for Java Business Integration.

In the business world, not all systems talk the same language. They use different
protocols and different forms of communications. Legacy systems in particular can
use proprietary protocols for external communication. The advent and acceptance of
XML has been greatly beneficial in allowing systems to be easily integrated, but XML
itself is not the complete solution.

When some systems were first developed, they were not envisioned to be able
to communicate with many other systems; they were developed with closed
interfaces using closed protocols. This, of course, is fine for the system developer,
but makes system integration very difficult. This closed and proprietary nature
of enterprise systems makes integration between enterprise applications very
difficult. To allow enterprise systems to effectively communicate between each other,
system integrators would use vendor-supplied APIs and data formats or agree on
common exchange mechanisms between their systems. This is fine for small short
term integration, but quickly becomes unproductive as the number of enterprise
applications to integrate gets larger. The following figure shows the problems with
traditional integration.

As we can see in the figure, each third party system that we want to integrate with
uses a different protocol. As a system integrator, we potentially have to learn new
technologies and new APIs for each system we wish to integrate with. If there are
only two or three systems to integrate with, this is not really too much of a problem.
However, the more systems we wish to integrate with, the more proprietary code we
have to learn and integration with other systems quickly becomes a large problem.

To try and overcome these problems, the Enterprise Application Integration (EAI)
server was introduced. This concept has an integration server acting as a central
hub. The EAI server traditionally has proprietary links to third party systems, so the
application integrator only has to learn one API (the EAI server vendors). With this
architecture however, there are still several drawbacks. The central hub can quickly
become a bottleneck, and because of the hub-and-spoke architecture, any problems
at the hub are rapidly manifested at all the clients.

Enterprise Service Bus

To help solve this problem, leading companies in the integration community
(led by Sun Microsystems) proposed the Java Business Integration Specification
Request (JSR 208) (Full details of the JSR can be found at http://jcp.org/en/jsr/
detail?id=208). JSR 208 proposed a standard framework for business integration
by providing a standard set of service provider interfaces (SPIs) to help alleviate the
problems experienced with Enterprise Application Integration.

The standard framework described in JSR 208 allows pluggable components to be
added into a standard architecture and provides a standard common mechanism for
each of these components to communicate with each other based upon WSDL. The
pluggable nature of the framework described by JSR 208 is depicted in the following
figure. It shows us the concept of an Enterprise Service Bus and introduces us to the
Service Engine (SE) component:

JSR 208 describes a service engine as a component, which provides business
logic and transformation services to other components, as well as consuming
such services. SEs can integrate Java-based applications (and other resources), or
applications with available Java APIs.


	Service Engine is a component which provides (and consumes) business
	logic and transformation services to other components. There are
	various Service Engines available, such as the BPEL service engine
	for orchestrating business processes, or the Java EE service engine for
	consuming Java EE Web Services. We will discuss some of the more
	common Service Engines later in this chapter.

The Normalized Message Router

As we can see from the previous figure, SE’s don’t communicate directly with each
other or with the clients, instead they communicate via the NMR. This is one of the
key concepts of JBI, in that it promotes loose coupling of services.

So, what is NMR and what is its purpose? NMR is responsible for taking messages
from clients and routing them to the appropriate Service Engines for processing.
(This is not strictly true as there is another standard JBI component called the Binding
Component responsible for receiving client messages. Binding Components are
discussed in Chapter 4. Again, this further enhances the support for loose coupling
within JBI, as Service Engines are decoupled from their transport infrastructure).

NMR is responsible for passing normalized (that is based upon WSDL) messages
between JBI components. Messages typically consist of a payload and a message
header which contains any other message data required for the Service Engine to
understand and process the message (for example, security information). Again, we
can see that this provides a loosely coupled model in which Service Engines have no
prior knowledge of other Service Engines. This therefore allows the JBI architecture
to be flexible, and allows different component vendors to develop standard
based components.


	Normalized Message Router enables technology for allowing messages to
	be passed between loosely coupled services such as Service Engines.

The figure below gives an overview of the message routing between a client
application and two service engines, in this case the EE and SQL service engines.

In this figure, a request is made from the client to the JBI Container. This request
is passed via NMR to the EE Service Engine. The EE Service Engine then makes
a request to the SQL Service Engine via NMR. The SQL Service Engine returns a
message to the EE Service Engine again via NMR. Finally, the message is routed back
to the client through NMR and JBI framework. The important concept here is that
NMR is a message routing hub not only between clients and service engines, but also
for intra-communication between different service engines.

The entire architecture we have discussed is typically referred to as an Enterprise
Service Bus.


	Enterprise Service Bus (ESB) is a standard-based middleware architecture
	that allows pluggable components to communicate with each other via a
	messaging subsystem.

Now that we have a basic understanding of what a Service Engine is, how
communication is made between application clients and Service Engines, and
between Service Engines themselves, let’s take a look at what support the NetBeans
IDE gives us for interacting with Service Engines.

What is XPath?

krishnas — Fri, 03 Apr 2009 14:54:47 +0000

Connect to us ( @twitter | @facebook )

Processing XML documents with Oracle JDeveloper 11g

While a number of books on XML are available, none covers XML support in Oracle JDeveloper. Welcome to Processing XML documents with Oracle JDeveloper 11g, a book that will teach you about using Oracle XML technologies in Oracle JDeveloper. XML is the standard medium of data exchange. Examples of data exchange using XML are web feeds, which include RSS feeds and Atom feeds, and XML messages in web services. Java is the language most commonly used to process XML.

Among the IDEs, Oracle JDeveloper has the most XML features. Some of the graphical XML features in JDeveloper are an XML editor to create an XML document, an XML schema editor to model an XML schema, and an XPath explorer to process XPath expressions. JDeveloper also provides built-in support for JAXB compilation. JDeveloper includes an integrated application server—the WebLogic Server—for running XML-based applications. Oracle XML Developer Kit (XDK) provides a set of components, tools, and utilities for developing XML-based applications. The XDK 11g libraries are included with Oracle JDeveloper 11g.

The objective of this book is to discuss XML development in Oracle JDeveloper. We shall use JDeveloper 11g, the latest version of JDeveloper. As developers commonly use an IDE for processing XML and developing XML applications, the book covers all aspects of XML development, which include:

Creating an XML document
Validating an XML document with an XML schema
Transforming an XML document
Addressing elements/attributes in an XML document using XPath

We shall use the Oracle XDK 11g for Java to develop XML applications. We shall also discuss Oracle XML Publisher and Oracle Berkeley DB XML. By the end of this book, you should know everything there is to know about XML and JDeveloper.

What This Book Covers

Chapter 1: We discuss creating an XML document using Oracle’s XML Developer Kit (XDK) 11g in Oracle JDeveloper. We also discuss parsing an XML document using SAX and DOM Java APIs, which are also included in XDK 11g.

Chapter 2: We create an XML schema in the XML schema editor of Oracle JDeveloper. An XML schema represents the structure of an XML document. Subsequently, we instantiate an XML document from the XML schema.

Chapter 3: We discuss validating an XML document with an XML schema using the built-in feature to validate the schema and the XDK 11g schema validation APIs. We discuss three different APIs for schema validation: the XSDValidator, the SAX parser, and the DOM parser.

Chapter 4: We discuss XPath, which is used to address nodes in an XML document. We use XPath in the XPath Search GUI tool in Oracle JDeveloper 11g. We also use the XPath Java API in XDK 11g.

Chapter 5: We transform an XML document using the Transformation API for XML (TrAX), which is included in XDK 11g. We also discuss the XSLT extension functions.

Chapter 6: We parse and transform XML using the JSTL XML tag library in JDeveloper 11g.

Chapter 7: We load, save, and filter an XML document using the DOM 3.0 Load and Save APIs, which are provided in XDK 11g.

Chapter 8: We construct and validate an XML document using the DOM 3.0 Validation API, which is also included in XDK 11g.

Chapter 2: We discuss another built-in feature of JDeveloper 11g, the JAXB 2.0 compiler. We bind an XML schema to Java classes using the JAXB 2.0 compiler. Subsequently, we unmarshal an XML document and marshal an XML document using the compiled Java classes.

Chapter 10: We compare XML documents using the XMLDiff Java API included in XDK 11g.

Chapter 11: We convert an XML document to a PDF document using the Apache FOP Java API in JDeveloper.

Chapter 12: We create an MS Excel spreadsheet from an XML document in JDeveloper using the Apache POI Java API.

Chapter 13: We store an XML document in Oracle Berkeley DB XML, and subsequently query and update the XML document using both the Berkeley DB XML command shell and the Berkeley DB XML Java API. The Berkeley DB XML API is used in JDeveloper 11g.

Chapter 14: We create PDF reports in JDeveloper 11g using the Oracle XML Publisher Java API. We also merge PDF documents. We also create an XML report from a database table using the Data Engine API.

What is XPath?

As mentioned in the earlier chapters, XML documents can be used for the transfer of data. The data in an XML document may be retrieved either with the JAXP (Java API for XML Processing) DOM and SAX APIs, or with the JAXP XPath API. Addressing
an XML document with XPath has the advantage that a single node may be selected directly without iterating over a node set. With SAX and DOM APIs, node lists have to be iterated over to access a particular node. Another advantage of navigating an XML document with XPath is that an attribute node may be selected directly. With DOM and SAX APIs, an element node has to be selected before an element attribute can be selected. In this chapter we shall discuss XPath support in JDeveloper.

What is XPath?

XPath is a language for addressing an XML document’s elements and attributes. As an example, say you receive an XML document that contains the details of a shipment and you want to retrieve the element/attribute values from the XML document. You don’t just want to list the values of all the nodes, but also want to output the values of specific elements or attributes. In such a case, you would use
XPath to retrieve the values of those elements and attributes. XPath constructs a hierarchical structure of an XML document, a tree of nodes, which is the XPath data model. The XPath data model consists of seven node types. The different types of nodes in the XPath data model are discussed in the following table:

Node	Type Description
Root Node	The root node is the root of the DOM tree. The document element (the root element) is a child of the root node. The root node also has the processing instructions and comments as child nodes.
Element Node	This represents an element in an XML document. The character data, elements, processing instructions, and comments within an element are the child nodes of the element node.
Attribute Node	This represents an attribute other than the xmlns-prefixed attribute, which declares a namespace.
Text Node	The character data within an element is a text node. A text node has at least one character of data. A whitespace is also considered as a character of data. By default, the ignorable whitespace after the end of an element and before the start of the following element is also a text node. The ignorable whitespace can be excluded from the DOM tree built by parsing an XML document. This can be done by setting the whitespace-preserving mode to false with the setPreserveWhitespace(boolean flag) method.
Comment Node	This represents a comment in an XML document, except the comments within the DOCTYPE declaration.
Processing Instruction Node	This represents a processing instruction in an XML document except the processing instruction within the DOCTYPE declaration. The XML declaration is not considered as a processing instruction node.
Namespace Node	This represents a namespace mapping, which consists of a xmlns:-prefixed attribute such as xmlns:xsd=”http://www. w3.org/2001/XMLSchema”. A namespace node consists of a namespace prefix (xsd in the example) and a namespace URI (http://www.w3.org/2001/XMLSchema in the example).

Specific nodes including element, attribute, and text nodes may be accessed with XPath. XPath supports nodes in a namespace. Nodes in XPath are selected with an XPath expression. An expression is evaluated to yield an object of one of the following four types: node set, Boolean, number, or string.

	For an introduction on XPath refer to the W3C Recommendation for
	XPath (http://www.w3.org/TR/xpath). As a brief review,
	expression evaluation in XPath is performed with respect to a context
	node. The most commonly used type of expression in XPath is a location
	path . XPath defines two types of location paths: relative location paths
	and absolute location paths. A relative location path is defined with
	respect to a context node and consists of a sequence of one or more
	location steps separated by "/". A location step consists of an axis, a
	node test, and predicates.

An example of a location step is:

	child::journal[position()=2]

In the example, the child axis contains the child nodes of the context node. Node test is the journal node set, and predicate is the second node in the journal node set. An absolute location path is defined with respect to the root node, and starts with “/”. The difference between a relative location path and an absolute location path is that a relative location path starts with a location step, and an absolute location path starts with “/”.

XPath support in Oracle XDK 11g

As we discussed in Chapter 1, Oracle XML Developer’s Kit 11g, which is included in JDeveloper, provides the DOMParser class to parse an XML document and construct a DOM structure of the XML document. An XMLDocument object represents the DOM structure of an XML document. An XMLDocument object may be retrieved from a DOMParser object after an XML document has been parsed. The XMLDocument class provides select methods to select nodes in an XML document with an XPath expression.

In this chapter we shall parse an example XML document with the DOMParser class, obtain an XMLDocument object for the XML document, and select nodes from the document with the XMLDocument class select methods. The different select methods in the XMLDocument class are discussed in the following table:

Method Name	Description
selectSingleNode(String XPathExpression)	Selects a single node that matches an XPath expression. If more than one node matches the specified expression, the first node is selected. Use this method if you want to select the first node that matches an XPath expression.
selectNodes(String XPathExpression)	Selects a node list of nodes that match a specified XPath expression. Use this method if you want to select a collection of similar nodes.
selectSingleNode(String XPathExpression, NSResolver resolver)	Selects a single namespace node that matches a specified XPath expression. Use this method if the XML document has nodes in namespaces and you want to select the first node that is in a namespace and matches an XPath expression.
selectNodes(String XPathExpression, NSResolver resolver)	Selects a node list of nodes that match a specified XPath expression. Use this method if you want to select a collection of similar nodes that are in a namespace.

The example XML document that is parsed in this chapter has a namespace declaration mlns:journal=”http://www.xdk11g.com/xpath” for elements in the namespace with the prefix journal. For an introduction on namespaces in XML refer to the W3C Recommendation on Namespaces in XML 1.0 (http://www.w3.org/ TR/REC-xml-names/). catalog.xml, the example XML document, is shown in the
following listing:



   
	  
		 Instant ODP.NET Deployment
		 Mark A. Williams
	  
	  
		 Application Server Convergence
		 David Baum
	  
   
   
	  
		 Oracle Database 11g Redux
		 Tom Kyte
	  
	  
		 Declarative Data Filtering
		 Steve Muench

Setting the environment

Create an application (called XPath, for example) and a project (called XPath) in JDeveloper as explained in the earlier chapters. The XPath API will be demonstrated in a Java application. Therefore, create a Java class in the XPath project with File|New. In the New Gallery window select Categories|General and Items|Java Class. In the Create Java Class window, specify the class name
(XPathParser, for example), the package name (xpath in the example application), and click on the OK button.

To develop an application with XPath, add the required libraries to the project classpath. Select the project node in Application Navigator and select Tools|Project Properties. In the Project Properties window, select the Libraries and Classpath
node. To add a library, select the Add Library button. Select the Oracle XML Parser v2 library. Click on the OK button in the Project Properties window. We also need to add an XML document that is to be parsed and navigated with XPath.

To add an XML document, select File|New. In the New Gallery window, select Categories|General|XML and Items|XML Document. Click on the OK button. In the Create XML File window specify the file name catalog.xml in the File Name field, and click on the OK button. Copy the catalog.xml listing to the catalog.xml file in the Application Navigator. The directory structure of the XPath project is shown in the following illustration:

XPath search

In this section, we shall select nodes from the example XML document, catalog.xml, with the XPath Search tool of JDeveloper 11g. The XPath Search tool consists of an Expression field for specifying an XPath expression. Specify an XPath expression and click on OK to select nodes matching the XPath expression. The XPath Search tool has the provision to search for nodes in a specific namespace. An XML namespace is a collection of element and attribute names that are identified by a URI reference. Namespaces are specified in an XML document using namespace declarations. A namespace declaration is an xmlns-prefixed attribute in an element
that consists of a namespace prefix in the attribute name with the namespace URI as the attribute value.

If you want to select nodes in a specific namespace or nodes from different namespaces, first add the namespace Prefix and URI to the XPath Search tool using the Add button. Subsequently, include namespace prefixes in the XPath expression. The XPath Search tool is shown here:

To navigate catalog.xml with XPath, select catalog.xml in the Application Navigator and select Search|XPath Search.

In the following subsections, we shall select example nodes using absolute location paths and relative location paths. Use a relative location path if the XML document is large and a specific node is required. Also, use a relative path if the node from which subnodes are to be selected and the relative location path are known. Use an absolute location path if the XML document is small, or if the relative location path is not known. The objective is to use minimum XPath navigation. Use the minimum number nodes to navigate in order to select the required node.

Selecting nodes with absolute location paths

Nex t, we shall demonstrate with various examples of selecting nodes using XPath. As an example, select all the title elements in catalog.xml. Specify the XPath expression for selecting the title elements in the Expression field of the Apply an XPath Expression on catalog.xml window. The XPath expression to select all title elements is /catalog/journal/article/title. Click on the OK button to select the title elements.

The title elements get selected. Title elements from the journal:article elements in the journal namespace do not get selected because a namespace has not been applied to the XPath expression.

As an other example, select the title element in the first article element using the XPath expression /catalog/journal/article[1]/title. We are not using namespaces yet. The XPath expression is specified in the Expression field.

The title of the first article element gets selected as shown in the JDeveloper output:

Attribu te nodes may also be selected with XPath. Attributes are selected by using the ”@” prefix. As an example, select the section attribute in the first article element in the journal element. The XPath expression for selecting the section attribute is
/catalog/journal/article[1]/@section and is specified in the Expression field. Click on the OK button to select the section attribute.

The attr ibute section gets outputted in JDeveloper.

Selecting nodes with relative location paths

In the pr evious examples, an absolute location is used to select nodes. Next, we shall demonstrate selecting an element with a relative location path. As an example, select the title of the first article element in the journal element. The relative location path for selecting the title element is child::catalog/journal/article[position()=1]/ title. Specifying the axis as child and node test as catalog selects all the child nodes of the catalog node and is equivalent to an absolute location path that starts with /catalog. If the child nodes of the journal node were required to be selected, specify the node test as journal. Specify the XPath expression in the Expression
field and click on the OK button.

The title of the first article element in the journal element gets selected as shown here:

Selecting namespace nodes

XPath Searc h also has the provision to select elements and attributes in a namespace.To illustrate, select all the title elements in the journal element (that is, in the journal namespace) using the XPath expression /catalog/journal:journal/journal:
article/title. First, add the namespaces of the elements and attributes to be selected in the Namespaces text area. Prefix and URI of namespaces are added with the Add button. Specify the prefix in the Prefix column, and the URI in the URI column. Multiple namespace mappings may be added. XPath expressions that select namespace nodes are similar to no-namespace expressions, except that the namespace prefixes are included in the expressions. Elements in the default namespace, which does not have a namespace prefix, are also considered to be in a namespace. Click on the OK button to select the nodes with XPath.

The title elements in the journal element (in the journal namespace) get selected and outputted in JDeveloper.

Attributes in a namespace may also be selected with XPath Search. As an example, select the section attributes in the journal namespace. Specify the XPath expression to select the section attributes in the Expression field and click on the OK button.

Section attributes in the journal namespace get selected.

Selecting nodes with XPath API

In the previous section, XML document nodes were selected automatically with the XPath Search tool in JDeveloper. In this section, we shall select nodes with the XPath API in the XPathParser class. JDeveloper XPath searches with the XPath Search tool are for the convenience of the developer as they find nodes faster than when looking through the XML file. The XPath searches, using the XPath API, actually let your application find nodes via XPath.

The XMLDocument class has select methods to select nodes with an XPath expression. A single node may be selected or a NodeList of nodes may be selected. Nodes declared in a namespace may also be selected. First, we need to import the oracle.xml.parser.v2 package that has the XMLDocument class and the parser class DOMParser, from which an XMLDocument may be obtained.

	import oracle.xml.parser.v2.*;

Creating the DOM parser

Next, we need t o parse an XML document and create a DOM structure for the XML document before being able to select nodes with XPath. Therefore, create a DOMParser using:

	DOMParser domParser=new DOMParser();

The DOMParser class, which extends the XMLParser class, has overloaded the parse methods to parse an XML document from different input sources. An XML document may be parsed from InputSource, InputStream, Reader, String, or URL. In the example application XPathParser.java, we shall parse an example document from a FileReader.

Create a FileReader object from a File object and parse it with the parse(Reader) method as shown in the following listing:

	domParser.parse(new FileReader(xmlDocument));

Variable xmlDocument is the File representation of the XML document catalog.xml. The class that provides XPath functionality is XMLDocument. Obtain an XMLDocument object from the DOMParser object with the getDocument() method.

	XMLDocument document=domParser.getDocument();

Method selectS ingleNode(String)

The XMLDocument class method selectSingleNode(String) selects a single node specified by an XPath expression. If more than one nodes match the XPath expression, the first node that matches the XPath expression gets selected. As an example, select the title of the first article node with section attribute value ORACLE DEVELOPER. The title element is selected with the selectSingleNode(String) method as shown here:

	XMLNode titleNode=(XMLNode)document.selectSingleNode("/catalog/
	journal/article[@section='ORACLE DEVELOPER']/title");

The title element value may be selected by first selecting the text node in the title element node using the getFirstChild() method and subsequently selecting the text node value using the getNodeValue() method, as shown in the following listing:

	String title=titleNode.getFirstChild().getNodeValue();

As another example of the selectSingleNode(String) method, select the author of the article with the title Oracle Database 11g Redux, as shown here:

	XMLNode authorNode=(XMLNode)document.selectSingleNode("/catalog/
	journal/article[title= Oracle Database 11g Redux']/author");

The author element text value is outputted by first selecting the text node within the author element node using the getFirstChild() method and subsequently selecting the text node value using the getNodeValue() method, as shown here:

	String author=authorNode.getFirstChild().getNodeValue();

The XMLDocument class selectSingleNode(String) may also be used to select an attribute node. As an example, select the section attribute of the second article in the journal of date March-April 2008:

	XMLNode sectionNode=(XMLNode)document.selectSingleNode("/catalog/
	journal[@date=March-April 2008]/article[2]/@section");

The section node value may be selected with the getNodeValue() method:

	String section=sectionNode.getNodeValue();

Method selectNodes(String)

The XMLDocument class method selectNodes(String XPathExpression) selects all the nodes specified by an XPath expression. As an example, select all the title elements for the journal of date March-April 2008, as shown in the following listing:

	NodeList nodeList=document.selectNodes("/catalog/journal[@date='March-
	April 2008']/article/title");

The method selectNodes(String) returns a NodeList that may be iterated over to output title elements:

	for(int i=0; i
The method selectNodes(String) may also be used to select attribute nodes. For example, select all the section attributes for the articles in the journal of date March-April 2008:
	NodeList
	nodeList=document.selectNodes("/catalog/journal[@date='March- April
	2008]/article/@section");

The NodeList of section nodes may be iterated over to output section node values as shown in the following listing:
	for(int i=0; i
Method selectSingleNode(String,NSResolver)
The XMLDocument class method selectSingleNode(String XSLPattern, NSResolver resolver) selects a single node specified by an XPath expression. NSResolver is used to resolve any namespace prefixes that may occur in the XPath expression.
To select nodes in a namespace, create a class (for example, CustomNSResolver) that implements the NSResolver interface. In the implementation class, implement the NSResolver method resolveNamespacePrefix(String prefix) as shown in the following listing:
	class CustomNSResolver implements NSResolver{
	   public java.lang.String resolveNamespacePrefix(java.lang.String
	   prefix){
	      if(prefix.equals("journal")){
		 return new String("http://www.xdk11g.com/xpath");
	      }
	   }
	}

The resolveNamespacePrefix method accepts a prefix and returns a URI.Create an NSResolver object. Set the namespace prefix to resolve using the resolveNamespacePrefix method:
	CustomNSResolver resolver=new CustomNSResolver();
	resolver.resolveNamespacePrefix("journal");

In the example XML document, catalog.xml, one of the journal elements is in the journal namespace. As an example, select the section attribute in the journal namespace in the first article element (in journal namespace) in the journal element (in journal namespace). The section attribute value will be outputted with the getNodeValue() method, as shown in the following listing:
	XMLNode sectionNode= (XMLNode)document.selectSingleNode("/catalog/
	journal:journal/journal:article/@journal:section", resolver);
	section=sectionNode.getNodeValue();

As a contrast b etween the selectSingleNode method that takes an NSResolver and the selectSingleNode method that doesn’t, the method that doesn’t take an NSResolver does not select nodes in a namespace. On the other hand, the one thatdoes selects nodes in a namespace. If the method that does not take an NSResolver is invoked with an XPath expression containing namespace nodes, the following error is generated:
	XSLException Namespace prefix 'journal' used but not declared.

Method selectNodes(String,NSResolver)
The XMLDocument class method selectNodes(String XPathExpression, NSResolver resolver) selects all the namespace nodes resolved by an NSResolver that are specified in an XPath expression. NSResolver is used to resolve any prefixes that may occur in the XPath expression. For example, select all the title elements in journal (in journal namespace) of date (in journal namespace) November-December 2008, as shown in the following listing:
	NodeList nodeList=document.selectNodes("/catalog/journal:journal[@
	journal:date='November-December 2008']/journal:article/title",
	resolver );

The namespace prefix journal in the XPath expression is resolved with an NSResolver object. The NodeList returned by the selectNodes(String, NSResolver) method may be iterated over to output the title elements.
	for(int i=0; i
Running the Java application
The Java progra m XPathParser.java is used to select nodes from the XML document catalog.xml. The Java application is listed with additional explanations about the application as follows:

First, we import the required packages from XDK 11g.
	import oracle.xml.parser.v2.*;
	import java.io.*;
	import org.xml.sax.SAXException;
	import org.w3c.dom.*;


Next, we add the XPathParser Java class declaration.
	public class XPathParser{


We define the parseDocument method to parse an XML document with the DOMParser.

	public void parseDocument(File xmlDocument){
	   try{


Next, we create a DOMParser object and parse the XML document.
	DOMParser domParser=new DOMParser();
	domParser.parse(new FileReader(xmlDocument));
	XMLDocument document=domParser.getDocument();


We specify the NSResolver object to resolve namespaces.
	CustomResolver resolver=new CustomResolver();
	resolver.resolveNamespacePrefix("journal");


Next, we select nodes using the selectSingleNode(String) method.
	XMLNodetitleNode=(XMLNode)document.selectSingleNode
	("/catalog/journal/article[@section=' ORACLE DEVELOPER']/title");
	String title=titleNode.getFirstChild().getNodeValue();
	System.out.println("Title of first Article in ORACLE DEVELOPER
	Section (with nodes not in any namespace) is "+ title);
	XMLNode authorNode=(XMLNode)document.selectSingleNode("/catalog/
	journal/article[title= Oracle Database 11g Redux']/author");
	String author=authorNode.getFirstChild().getNodeValue();
	   System.out.println("Author of Title Oracle Database 11g Redux
	   is "+ author);
	   XMLNode sectionNode=(XMLNode)document.selectSingleNode
	   ("/catalog/journal[@date=March-April 2008']/article[2]
	   /@section");
	String section=sectionNode.getNodeValue();
	System.out. println("Section of 2nd Article in Journal of date
	March-April 2008 is "+ section);


We select nodes using the selectNodes(String) method.
	NodeList nodeList = document.selectNodes("/catalog/journal[@date=
	'March-April 2008']/article/title");
	System.out.println("Article Titles published in journal of March-
	April 2008 are: ");
	for(int i=0; i

Next, we select nodes using the selectSingleNode(String,NSResolver) method.
	sectionNode=(XMLNode)document.selectSingleNode("/catalog/journal:
	journal/journal:article/@journal:section", resolver);
	section=sectionNode.getNodeValue();
	System.out.println("Section of first article in first journal
	(nodes being in journal namespace) is "+section+" ");
	System.out.println("Titles for articles in journal of date
	November-December 2008 (journal, article, and date nodes being in
	journal namespace) are ");


We also select nodes using the selectNodes(String,NSResolver) method.
	nodeList=document.selectNodes("/catalog/journal:journal[@journal:
	date= 'November-December 2008']/journal:article/title",
	resolver );
	for(int i=0; i

We add the Java class that extends the NSResolver class.
	class CustomResolver implements NSResolver{
	public java.lang.String
	resolveNamespacePrefix(java.lang.String prefix){
	if(prefix.equals("journal")){
	   return new "http://www.xdk11g.com/xpath";
	}else
	   return null;
	   }
	}


Finally, we define the main method in which we create an instance of the
	XPathParser class and invoke the parseDocument method.
	   public static void main(String[] argv){
	      XPathParser parser=new XPathParser();
	      parser.parseDocument(new File("catalog.xml"));
	   }
	}



To run the XPathParser.java application in JDeveloper, right-click on the XPathParser.java node in the Application Navigator, and select Run. The output from the XPathParser.java application is shown in the following illustration:
Summary
In this chapter you learned about XPath support in JDeveloper 11g. JDeveloper provides an XPath Search GUI tool to select nodes from an XML document using XPath. We selected nodes using absolute location paths and relative location paths, and also selected namespace nodes. We discussed the XDK’s XMLDocument class select methods to select elements and attributes in an XML document with XPath. The select methods may be used to select single nodes or collections of nodes. The select methods may also be used to select nodes in a namespace. In the next chapter, you will learn about XSLT(Extensible Stylesheet Language Transformation) support in JDeveloper.

XML Schema Elements – Part2

JavaBeat — Wed, 25 Mar 2009 04:44:06 +0000

Connect to us ( @twitter | @facebook )

Complex Elements

Complex elements are those which contain other elements as children or these elements have attributes. Empty elements and elements containing only text are also considered complex. The following is an examples of complex element


	745821
	Tim
	35000
	Insurance

Define Complex Type in XML schema

Complex types can be defined in XML schema as demonstrated in this example:

Define empty elements

Consider the following XML element:

This empty element can be defined in XML schema as follows:

Here we can see that in the definition we dont define any child elements. We just define the attribute.

Define text only elements

Consider the following XML element:

BFS

The above element can be defined in XML schema as follows:

Here, we define that the content of the complex type is simple. In schema terms simple means plain text. The xs:extension is used to declare the type of the data.

Define Mixed Content

Sometimes an XML element can contain elements and text combined. Consider the following example:


The employee 134567
belongs to BFS
and his salary is 56430

The above fragment can be defined in XML schema as follows:

In the defined XML schema we use the attribute mixed and set its value as true. This indicates that the XML element can contain other elements and simple text as it children

XSD Indicators

Using XSD Indicator a desicion can be made about how to use Complex types elements in a XML document. The indicators are basically divided into three groups :

Order indicators
Occurrence indicators
Group indicators

Let us know look at each of these categories.

Order Indicators

The order indicators define the ordering of the elements or the sequence in which the elements appear in the XML document. This group of indicators has three types of indicators :

All
Choice
Sequence

All

Using the All indicator allows the child elements to appear in any order. However, it sets a restriction that each child must appear only once. Lets look at an example :

Choice

The Choice indicators specifies that out of all the child elements one can appear. Lets look at an example:

Sequence

This indicator specfies that the child elements should follow the specified order :

Occurrence Indicators

The occurrence indiactor defines the number of times an element can appear. This group has two differetn types:

maxOccurs
minOccurs

maxOccurs

The maxOccurs element sets an upper limit on the number of times an element can upper. Lets looks at an example:

minOccurs

The minOccurs element sets the lower imit on the number of times an element can upper. Lets looks at an example:

Group Indicators

Group indicators allow us to define a group of elements

Group name
attributeGroup name

Group Name

The group indicator is used to define a group of elements. Once defined the group can be referenced in other places within the XML schema. Lets look at an example :

In the above example we define a group named projectGroup. Now we will see how to refer this group in other places :

After making a reference to the projectGroup the employee element gets a total of six child elements:
empId, name, salary, domain, projectname, technology

Attribute Groups

The attribute group is used to group together a set of attributes. Once defined the group can be referenced in other elements to define the attributes for a element. Lets look at an example :

The Element

With the use of the any element an XML schema can can extend another XML schema. Lets look at an example :

Filename : employee.xsd

Filename : children.xsd

The XML file can use components from both the files:


	143233
	John
	34500
	Insurance
	
		ISD
		.NET

XSD Data Types

String

The string data type is used to store characters and strings. For e.g:

	
	
		XML Schema
		
	
	
		XML
		John

Date

The date type represents a date. The date represented by using the date datatype is specified in the following format : YYYY-MM-DD.
For e.g:



	XML Schema
	



	XML
	2007-03-27

Numeric

The numeric data types are of two types:

Decimal

The decimal data type is used to represent decimal numbers. For e.g:



	XML Schema
	


	XML
	678.50

Integer

The integer data type is used to represent integers. For e.g:



	XML Schema
	


	XML
	678.50

Other Datatypes

Boolean

The boolean datatype represents the value true or false.E.g:

XML Schema
XML	John

[Note: If one wants to test these examples then you should have a suitable XML editor. By simply copying the files in your system and executing them in the browser wont produce the expected output.]

XML Reference

XML Schema Elements

JavaBeat — Sat, 21 Mar 2009 04:43:29 +0000

Connect to us ( @twitter | @facebook )

XML schema is a language for describing the contents and structure of a XML document. It basically creates a blue print of the actual XML document by describing everything about the elements which can appear in the document. By creating a XML schema we make the XML document conform to the rules defined in the XML schema. It essentially says that the XML document cant break the rules defined in the XML schema document.

Lets create a sample XML schema document empSchema.xsd:

Lets create a XML document employee.xml:



	745821
	Tim
	35000
	Insurance

In the XML document above we see that the document is referring to a XSD document[xsi:noNamespaceSchemaLocation="empSchema.xsd"]. XSD is nothing but a file which defines XML schema.
I will explain the details of the XML schema document as we go along. The above example is just supposed to give you a feel of what an XML schema looks like and how to refer to the XSD from a XML file.

XML Schema Elements

schema

Every XML schema starts with element as the root. The attribute xmlns:xs=”http://www.w3.org/2001/XMLSchema” says that the elements in the XML document belong to the “http://www.w3.org/2001/XMLSchema” namespace and each of the elements that belong to this namespace should be prefixed with the xs.

Simple Type

A simple type element cannot contain any other elements or attributes. It can contain only text data. For E.g:



Syntax:



XML Schema:



XML:
Daniel

The allowed datatypes in XML schema are :

Attributes

An attribute provides additional information about the element. Simple types cannot have attributes. However the attribute itself are of type simple. Let us now look at the syntax and an example of how to define attributes in XML Schema:



Syntax:



XML Schema:



XML:
Daniel

Content Restrictions

When an element or an attribute is defined with a particular data type, it essentially means that the element or attribute cant be assigned a value which is of some other type. In XML schema we can define custom restrictions on elements. Such restrictions are called facets.

Value restrictions

Using value restrictions the XML schema places a restriction that the value of the element should be between a allowed range.In the following example element a restriction is placed on the salary element that its value cannot be less that zero and more than 85000.
In case it happens then the XML document will not validate:

Restriction on a set

In set restriction the value of an element should be set from only an allowed set of values. In the following example the value of the domain element is limited to a certain set of values:

Restriction on a series

In such type of restriction we can use any valid regular expression syntax to define the restrictions. In the following example we define a restriction that the number should be between 0 and 9.

Restriction on a whitespace characters

These restrictions define how the whitespace characters are handled in the XML document. The restriction can be placed using the following syntax:

1
2
3

or

The attribute value preserve says that the whitespace characters will not be removed by the XML processor. The attribute value replace says that the following characters will be replaced by spaces :
line feeds, tabs, spaces, and carriage returns. Lets looks at an example now :

Restriction on the length

This places a restriction on the allowed numbers of characters. The following example places a restriction that the employee id cannot be more than 6 characters