Friday, August 24, 2007

Favorite svn commands

Recently I switched from Windows to Linux, or more specifically Ubuntu 7.0.4. With a couple of minor issues, everything is working great so far. One of the main reasons for changing was to be faster and better at what I do, and I think linux can help me achieve some that.
One common thing I feel makes linux developers faster is knowing commands and not requiring GUIs. GUIs take a long time to load and refresh compared to just opening a file in vi or vim. On windows I loved SmartSVN and would recommend it to anyone; in fact I have had to install it on linux until I have been converted. At the same time I have enjoyed learning the svn commands, which by the way are 100 times easier than cvs commands. Most cvs commands require options to be effective (cvs update -Pd). Not so with svn.

Here is a list of favorite svn commands I have come to love. Also included are recommendations from friends.

  1. svn help . For example svn help update
  2. svn status. List modified or uncommitted files
  3. svn update. Get the latest code and update your modified files
  4. svn commit filename -m "Commit Message". Commit the file. filename is optional
  5. svn diff. Do a diff on locally modified files.
  6. svn diff -r M:N. Performs a diff on the revisions M and N
  7. svn merge -r M:N. Revert back to a previous version
  8. svn log -v. Gives you a verbose log of everything that has happened
  9. svn st | grep "?" | awk '{print $2}' | xargs svn add. Handy command for those who go days without committing and need an easy way to commit uncommitted files.
  10. svn propedit svn:ignore. Tells subversion to ignore certain files or directories.
  11. svn revert filename. Takes the filename out of source control. Handy when commnd #9 adds files you didn't intend to add.
Also there are shortcuts to most of these subcommands. For example svn status is also svn stat or svn st. Just run svn help to get a list of shortcuts.

Finally, don't be disappointed if you are a windows developer. You can use svn in cygwin the same way.

Monday, August 20, 2007

Using the JBI JavaEE ServiceEngine

Update April 10th, 2008
An update has been provided on how to use the Java EE SE in the latest version of Netbeans. Please go here to read this update.
----------

In order to familiarize myself with different JBI components I would like to walk through an example using the JBI JavaEE Service Engine written by Sun. So what is the JavaEE Service Engine? It's a highly useful JBI component providing a bridge between the web container (glassfish) and the JBI container (OpenESB), or more specifically the NMR (Normalized Message Router). It's useful because it allows EJBs and Servlets, packaged as web services, to communicate directly with JBI components and vic versa. Consequently, this increases performance since the request/response doesn't have to travel in and out of the HTTP BC and the glassfish Servlet container.

So if you are writing EJB 3.0 web services, you have alot to gain by using BPEL and JBI in general, and you need to look into using the JavaEE SE. The following is a simple example of how to use it.

If you haven't already, first start out by downloading the latest OpenESB installer which includes Netbeans 6.0. Then follow this video tutorial to create a Composite Application consisting of a BPEL process invoking an EJB web service (but not using the JavaEE SE yet). This will help us create our web service and get familiar with BPEL and Netbeans. If you prefer to skip this step I have uploaded the EJB Module, BPEL Module, and Composite Application for convenience. After completing this step your casa file should look like this (in netbeans, right click on the CompositeApplication and click Edit Application Configuration):



Notice there are no endpoints for the JavaEE SE. Here is the sequence of events when running the test included in the HelloBPELCompositeApp:
http client --> inbound HTTP BC --> BPEL SE --> outbound HTTP BC --> Glassfish Servlet Container --> invoke Hello web service --> response.

The next step is to actually utilize the JavaEE SE advantages. This only requires adding the EJB module as a JBI module to the HelloBPELCompositeApp. In JBI you can add multiple JBI Modules (Service Units) to Composite Applications (Service Assembly). In netbeans, right click on HelloBPELCompositeApp and click Add JBI Module. Select Hello, which is the EJB Module. If you expand the JBI Modules directory under HelloBPELCompositeApp, you should see Hello.jar and HelloBPEL.jar. Before we can redeploy we first must modify the casa file to remove the existing connection between the outbound HTTP endpoint and glassfish. Reopen the casa file (in netbeans, right click on the CompositeApplication and click Edit Application Configuration), and highlight the line going between the HelloRole_partnerRole Consumer to the HelloPort Provider. Your casa file should look like this now and this verifies that we are going through the JavaEE SE:



--
April 8th, 2008 Update
Since this post is pretty popular I have an update since this post doesn't work with the latest version OpenESB+Netbeans. Not only do you have to remove the line as described above, but you also need to remove the SOAP Port, otherwise you will receive an "java.net.BindException: Already bound: 8080". So in the image above highlight and delete the HelloPort.

Also in newer versions of Netbeans access to the CASA file is done by double clicking on the Service Assembly file under your Composite Application project.
--

Rebuild HelloBPELCompositeApp by right clicking and choosing Clean and Build. Then undeploy and deploy HelloBPELCompositeApp. Finally rerun the test and it should pass. Again we know the JavaEE SE is being used based off the casa file. The new sequence of events are:
http client --> inbound HTTP BC --> BPEL SE --> JavaEE SE --> invoke Hello web service --> response.

It should be obvious where the performance improvement is located. That is what makes the JavaEE SE so powerful. For convenenice, here is the final netbeans Composite Application project with the modified casa file.

If you are curious to know what netbeans was doing under the covers for us when creating the EJB Module Service Unit here is a quick explanation. In netbeans and File view you can expand the build directory under HelloBPELCompositeApp. Next expand the Hello.jar service unit. There you will see the jbi.xml and an empty sun-resources.xml. The jbi.xml file defines the endpoints the JavaEE SE must activate. These endpoints will be used by the BPEL SE consumer endpoint. Also interesting is it includes a binary of the Hello Service (Hello.class).

Wednesday, August 8, 2007

Setting up a simple maven2 project in less than 1 minute

Ever need to create a new maven2 project? Was your next step to copy and paste an existing maven2 project and rename all the directories, package folders, and oh yeah don't forget to remove those SCM (cvs/svn) hidden directories. That's not all, don't forget to update the pom's groupId, artifactId, and everything else under the POM sun.

Using the maven-archetype-plugin you can create simple projects in a matter of seconds. "Archetypes are a simple and useful way to bootstrap new development across your organization, and urge your developers to follow a similar project pattern. Archetypes are a template of a Maven project used to generate skeleton layout for projects of any desired type in a consistent way" (Maven: The Definitive Guide).

The default archetype is quickstart, and generates a simple Java project with some source and a unit test. Here is how you can use the quickstart archetype to create a maven2 project in seconds saving you from the copy/paste world:

mvn archetype:create -DgroupId=com.gestalt.jbi.rss.binding -DartifactId=rss-binding-installer

Thats it! Next you can run mvn clean install and you now have a simple Java project created.

If a simple J2SE project isn't what you need then check out these other 10 archetypes. Most notably are:

  1. maven-archetype-archetype - used to create a simple project that can be used to build other archetypes
  2. maven-archetype-j2ee-simple - build a simple j2ee project
  3. maven-archetype-mojo - in maven2, mojos comprise a maven plugin, so this archetype creates a project that gets you set to build your own maven plugin
Plus there are many many more available in the open source community. For example when working with Apache ServiceMix and maven2, use their maven archetypes to build Service Engines or Binding Components. They also have archetypes to help simplify creating Service Units/Service Assemblies for their various components. Sun also has support for archetypes to create components as well.

Most common WSDL stumbling block

When it comes to helping people debug WSDL issues, the #1 overlooked and misunderstood problem is usually whether to specify type or element as the attribute to the element. If you are creating web services and defining WSDLs you must understand this significant difference as it will effect the consumers of your services.

All my examples and information where referenced from the book Building Web Services with Java. I would highly recommend this book.

Simple WSDL
Let's first begin with snippets from a simple WSDL.

<definitions name="PriceCheck">
<types>
<xsd:schema>
<xsd:element name="sku" type="xsd:string"/>
<xsd:complexType name="availabilityType"
<xsd:sequence>
<xsd:element ref="sku"/>
<xsd:element name="price" type="xsd:double"/>
<xsd:element name="quantityAvailable" type="xsd:integer"/>
</xsd:sequence>
</xsd:complexType>
<xsd:element name="StockAvailability" type="availabilityType"/>
</xsd:schema>
</types>
<message name="PriceCheckRequest">
<part name="sku" element="sku"/>
</message>
<message name="PriceCheckResponse">
<part name="result" element="StockAvailability"/>
</message>
<portType>
<operation name="checkPrice">
.......
<binding>
.......
<service>
.......
</definitions>
WSDL Parts
A part element is made up of two properties: the name of the part and the kind of the part. The name property is represented by the name attribute, which must be unique among all the part child elements of the message element. The kind property of the part is defined as either a type attribute (a simpleType or complextType from the XSD schema type system) or an element attribute (also defined by referring to an element defined in the XML schema). You can't use both an element attribute and a type attribute to define the same part.

The choice of using element or type when defining the part is very important. The most common mistake is using the type attribute and referencing an XSD element or using the element attribute and referencing an XSD simpleType or complexType.

Use of element
When you use the element attribute, you're specifying that the SOAP should be precisely that XML element. For example, the PriceCheckRequest example specifies that the XML element named sku must be used as the body of the messsage. Here is a snippet of what the SOAP would look like:

<soap:Envelope>
<soap:Body>
<sku>123</sku>
</soap:Body>
</soap:Envelope>
Note how the SOAP contains exactly the specified sku element. The element attribute should be used to define the type of the part when the Web service is meant to be document oriented (which is defined in the binding). Whenever the element attribute is used, its value must refer to another global XML element defined or imported in an XML schema.

This not only applies to requests but responses as well. For example, here is what the SOAP would look like for PriceCheckResponse:

<soap:Envelope>
<soap:Body>
<StockAvailability>
<sku>123</sku>
<price>100.0</price>
<quantityAvailable>12</quantityAvailable>
</StockAvailability
</soap:Body>
</soap:Envelope>

Use of type
The PriceCheckRequest could have been built differently, using a part defined with the type attribute, like this:

<message name="PriceCheckRequest">
<part name="sku" type="xsd:string"/>
</message>

Here is an example of the SOAP using the RPC-style where checkPrice is the name of the operation defined in the WSDL:

<soap:Envelope>
<soap:Body>
<checkPrice xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
<sku xsi:type="xsd:string">123</sku>
</checkPrice>
</soap:Body>
</soap:Envelope>
Summary
That is the difference between defining your part as an element or type. The most common style to use is document oriented and therefore the parts must use elements. If you use type in your parts, you need to use the RPC style.

Unfortunately all this isn't well documented. However there is good news. In WSDL 2.0 message and part elements have been removed. Instead you would use the names of the XML element declarations directly in the operations input, output, and fault messages.

Test Driven Development ROI

Ever think about the true benefits of tests and the value they provide you and your company? This article basically challenges developers to consider the ROI (Return On Investment) of every test. It has had a big impact on my software development habits by making me examine the benefits vs. the costs of writing tests.

Here is one of his most interesting comments: "... the developer is concentrating on testing before "coding" - the primary function is hence the development of tests, leading to a situation of "test-oriented development. This is where the production of tests becomes the overriding concern and output of a team, with the development of required functionality being secondary. When this occurs, the design, quality, and scope of the tests all become greater than that of the system actually being created". I am a firm believer in unit tests, but I hope I never fall into that category. We have a saying here at work, "I can get you about 90% confidence, but it's going to cost a lot to get that other 10%".

Oh yeah, its now Test First Development.

Also here is a follow up article to the original link above: When TDD Goes Bad #2. In it the author explains Mock oriented development and the lack of integration tests.

Wednesday, August 1, 2007

My de facto standard on WSDL styles

Here is my de facto standard reference on WDSL styles; bookmark it! When I first started writing Web Services I never knew their were 2 styles and 2 uses, or even that there was a style. As I gradually learned more about WSDLs it was difficult to find a good explanation of the different combinations. This article, written by Russel Butek on IBM developerWorks, explains how you determine which combination of style and use to choose. He provides advantages and disadvantages of each and shows WSDL and SOAP messages for each combination.

Overall when creating a Web Service you have 4 style/use options:

  1. RPC/encoded
  2. RPC/literal
  3. Document/encoded
  4. Document/literal
Along with these four is a recently new pattern which is commonly called document/literal wrapped.

Please read this article if you are unfamiliar with the different styles and uses. In general the most common style used is document/literal wrapped with document/literal in second. Most newer SOAP Stacks actually don't support RPC anymore; for examlpe cxf (aka xfire) and axis2.