This is a refresher about the HTTP protocol (citation: RESTful Web Services, 2007, L.Richardson, S. Ruby, O’Rielly Media Inc).

What is HTTP?

HTTP stands for Hypertext Transfer Protocol.

Using the analogy of a document and envelope…

HTTP is a document based protocol:

1. A client puts a document into an envelope and sends to a server.
2. The sever puts a response envelope into an envelope and sends to the client.

HTTP has strict standards about the type of envelope but not what goes inside it.

HTTP Request (Client)

The HTTP Method

Can be GET, POST, DELETE, PUT, OPTIONS, HEAD, PROFIND, COPY, MOVE

The Path

The URI to the right of the hostname – this becomes the address on the envelope.

Request Headers

These are key-value pairs that specify infomation about the envelope – there are 46 in all – some of them include: Host, User-Agent, Accept, Keep-Alive…

The Entity Body/Document/Representation

The document inside the envelope.  GET requests never have an entity body, all the information necessary is included in the path and request header.

In POST requests – the entity body could be structured XML to pass over a substantial amount of complex data.  Some web services may take this data and make objects from the XML and feed it into a database, however you do not necesarily have to use XML you can just use plain text, you also don’t have to put the data in a database – you can do what you want with data once you recieve it on the database.

The following shows an example of a GET reqeust to the BBC:

(Request-Line)    GET / HTTP/1.1
Host    www.bbc.co.uk
User-Agent    Mozilla/5.0 (Windows; U; Windows NT 5.1; en-GB; rv:1.9.0.11) Gecko/2009060215 Firefox/3.0.11
Accept    text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language    en-gb,en;q=0.5
Accept-Encoding    gzip,deflate
Accept-Charset    ISO-8859-1,utf-8;q=0.7,*;q=0.7
Keep-Alive    300
Proxy-Connection    keep-alive
Cookie    AMOS_PREF=sac%3Dg4; BBC-UID=e4c73e81d4fc55653460b7caa03036f31b6ba10990a0b114b4ffb881cf0ba6450Mozilla%2f5%2e0%20%28Windows%3b%20U%3b%20Windows%20NT%205%2e1%3b%20en%2dGB%3b%20rv%3a1%2e8%2e1%2e12%29%20Gecko%2f20080201%20Firefox%2f2%2e0%2e0%2e12; BBCNewsAudience=Domestic; BBCNewsAudcWght=-99; BBCMediaSelector=m%3Arm&b%3Abb&st%3Ah&ms3%3A4; hp=+acv+ba+neaj+hj+oab*+c1+g1ab+mc2+rad*+da+f1a7b7c7d7+i+kca+la

HTTP Response (Server)

HTTP Response Codes

The code tells the client what happened to their request – did it fail or was success achieved.   There are lots of codes, the most common you will have seen on the web is 404 – which means “Not Found” i.e. the web page was not found on the server.  A success code will usually be 200 i.e. if you got to see the web page you asked for.

Response Header

Pretty much the same as Request Headers e.g. Date, Server, Etag, Content-Type, Last-Modified…

The Entity Body/Document/Representation

In GET requests you actually get an entity body sent to you (or at least you should do!)   The Response Header also makes an important contribution here, like Content-Type – this will tell the client about the media-type to expect (there are many of these) but in the case of a browser rendering an HTML web page it will commonly be text/html.

N.B – media-type can also be referred to as MIME type, content type or data type.

The following is an example of a response from the BBC:

(Status-Line)    HTTP/1.1 200 OK
Via    1.1 BLADEWIN17
Connection    Keep-Alive
Proxy-Connection    Keep-Alive
Content-Length    110652
Date    Wed, 24 Jun 2009 16:00:01 GMT
Age    87
Content-Type    text/html
Server    Apache
Accept-Ranges    bytes
Keep-Alive    timeout=4, max=194

Objective: To develop a web service that is to be used internally by applications to retrieve and write data to an Oracle database.

I wanted to develop a web service that was designed with the REST framework in mind, SOAP is just too “noisy”, and overly complex.   The web service had to be able connect and interact with an Oracle database, it also had to return any data from the database as XML.  You can view the results directly from a web browser if it’s XML, but it is not really necessary as a web service is mostly a non-human readable resource.

So, I was developing with Java – and had to try an work out what the best tools, APIs would be, bearing in mind the myriad of tools out there on the web.  It took quite a while looking at all the various API’s out there (Spring, Hibernate, iBATIS, EclipseLink, Toplink – the list goes on), but I chose ones that matched the following criteria:
a) if a technology was already in use at work, then that had to be adopted – in order to stop a proliferation of different technologies being used, supported and maintained.

b) easy to use and understand.

c) have decent community support behind them – so if problems arise then at least someone out there may be able to lend a hand.

d) look likely to be well supported in the future without fading into obscurity in the next couple of weeks/months.

Choosing the Right Tools – My Software Stack

• Java IDE – is Eclipse Europa v3.3.2

• Apache Tomcat Application Server v5.5.17

• For the REST web service I chose – Restlet v1.1.4.

A really nice and clean well supported framework.  Some of the tutorials were a bit raw but they have improved of recent and the documentation is getting better all the time.  They are constantly improving the API and stable releases are issued on a resonably regular basis.  They are keen to adopt good standards and it was pleasing to see that WADL is supported in their extended APIs for Restlet.

• For Object Relational Mapping (ORM) with Oracle I chose Toplink  (version 10g Release 3 10.1.3.3.0) and the Workbench software- don’t even think about using raw JDBC API’s – it’s much less work to use Toplink rather than code everything from scratch.

• For XML to Object ORM, I chose Sun’s JAXB v2.0 implemenation – so, so, so much better than Toplinks crummy efforts (so I am saying Toplink is good for database ORM but not for XML ORM) – I spent so many wasted development hours on this piece of crud – so don’t use it unless you want to a miserable life as a developer.  JAXB is nice, its from Sun so it should conform to some form of standard.  The docs are good and it takes seconds to run the JAXB compiler from a command line along with your XSD schema and generate your Java classes.  Pretty good all round.

In my next post I explain how I used the above to create my REST web service.

Everything you need to know about parsing XML – without being baffled by long winded ramblings and flag waving for the latest/greatest frameworks.

There are 2 basic parsing strategies with XML.

1. DOM – Document/tree based strategy.
2. SAX – event based strategy.

DOM

• Simple.
• Nested tree structure.
• Process and query with XPath or other parser supported functions.
• Implements specific interface defined by W3C.
• You have to load the whole document into memory – so if the XML is big – then you have to watch out.
• Simple and large XML documents do not suit this style.
• Random access to the document.

SAX

• Complex to use.
• Event based.
• Starting/Ending tags, XML comments and entity declarations all raise events.
• Flexible – you can handle events when needed, and take action on those events as they are raised.
• Once events have been fired they are gone, you have to re-read the document again if you need to get back to the same bit of XML again.
• Malformed XML can cause the code to fall into exception – make sure your document is well formed before passing to the parser.

C# and Java XML Implementations

C#

• Look at System.Xml.XmlReader.
• DOM trees can be used via XmlDocument – and XPathDocument lets you interrigate the tree nodes via XPath.

Java (1.5)

• If you are using 1.5 you are in luck as this version includes the Apache Xerces project.
• Look at packages javax.xml.* – this also has XPath functionality.
• DOM functionality can be found in org.w3c.dom.*
• If you are using Java 1.4 and below, you will have to install Xerces.

Got one of these babies the other day to swap out my existing dud motherboard.  It is quite nice and also comes with a X-Fi sound module (SupremeFX X-Fi Audio Card) that plugs into the motherboard – bonus!

Problem is that the fit of this sound module conflicts with the motherboard layout i.e. it can rest on top of the mounting screw, as the hole for the mouting screw is right underneath where the sound module would go – this will cause a short and cause your PC not to start up i.e. you will be able to switch the PC on – but the fans will work for 3 seconds and then it cuts out.

Simple thing to do is remove the mouting screw that is resting against the sound module.  You don’t necessarily need all the mounting screws in the motherboard to make it secure.   After you have done this your PC should boot up normally.

I have seen from time to time XML from various examples/tutorials/forums – explanations that are confusing and others that are just plain WRONG!  Most of it comes down to the inappropriate use of XML elements and attributes.  I also happen to think this is one of the most confusing and ambiguous asepects of XML – but I think if you retain the following knowledge you should have little problems in forming your own correct XML documents.

Always bear in mind that “attribute” is essentially metadata i.e. something that describes something about the data.  I think a lot of people get confused with the actual terminology – “attribute”, thinking that the main element should have attribute data e.g.:

<part description="some part" price="£12.34" location="A1B2">

Don’t fall into that trap, it will cause you no end of problems, as W3School explains:

• attributes cannot contain multiple values (child elements can)
• attributes are not easily expandable (for future changes)
• attributes cannot describe structures (child elements can)
• attributes are more difficult to manipulate by program code
• attribute values are not easy to test against a DTD

I can’t think of a reason why you would want to store your data in such a way.  The correct way would be to do the following:

<part>
    <description>some part</description>
    <price>£12.34</price>
    <location>A1B2</location>
</part>

Each peice of data is represented in it’s own element tag and not stored as an attribute to some arbitary first element.

The rule to remember is – if it looks like data  then store as an element.  The next question you are probably thinking is – when should I use attributes then?  There are no hard and fast rules – annoying I know, but one possible scenario for using an attribute could be as an ID attribute – something that is not intrinsically part of the data but can be used to help identify or tell you something extra about the data.

Conclusion: Use elements to store data, use attributes to describe something about the data.

Just thought I’d quickly mention some good resources for learning the REST paradigm (having now moved on from SOAP web services.  These are basically resources I wish I had found on day 1.

The following is bearing in mind you are using the Restlet framework.

Again, a total lack of any decent, comprehensible tutorial material on the net, but I did unearth a gem from IBM’s website (you do have to register to download the doc, but it is free):

Build a RESTful Web service – An introduction to REST and the Restlet framework by Andrew Glover.

Also to back up your knowledge and to help you understand the above tutorial, I would suggest reading:

RESTful Web Services by Leornard Richardson and Sam Ruby from O’Reilly.

Enjoy!

PS – Hope to publish my findings on a making my first RESTful web service that writes into a database.

After ‘writing off’ Visual Inheritance – I still found that I was stuck with it in my application – just so many things depended on it working.  I’m still annoyed about it being buggy and doing unexpected things – but I have come up with a list of things to do in order to keep VI ticking over – maybe you will find these useful too:

• No abstract control types
• No constructor arguments
• Initialisation moved to Form_Load as opposed to the constructor
• No controls nested in another windows control e.g. toolstrip.
• Close all documents -> Clean -> Rebuild
• Restart Visual Studio

Want to know how connect to your AGS server and get a handle on IMap of your published AGS map service.  The following code should give you the basic bare bones code that you need in order to do that – note stuff in “” should be applicable to your environment.

BTW – I find that getting a handle on IMap is useful in a great many ArcObjects based programming – so just thought I should post.

private String _host = "myServerName";
private String _username = "joebloggs";
private String _password = "password";
private String _domain = "myDomainName";
public void connectToServer()throws IOException
    {
        try {
            IServerContext serverContext = null;
            IServerConnection serverConnection = new ServerConnection();
            ServerInitializer serverInitializer = null;
            IServerObjectManager som = null;

            serverInitializer = new ServerInitializer();
            serverInitializer.initializeServer(_domain, _username, _password);
            serverConnection.connect(_host);
            som = serverConnection.getServerObjectManager();
            serverContext = som.createServerContext("publishedMapServiceName", "MapServer");

            IMapServer mapServer = (IMapServer) serverContext.getServerObject();
            IMapServerObjects mapServObjs = (IMapServerObjects) mapServer;

            IMap map = mapServObjs.getMap(mapServer.getDefaultMapName());

            serverContext.releaseContext();

        } catch (UnknownHostException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        } catch (AutomationException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        } catch (IOException e) {
            // TODO Auto-generated catch block
            e.printStackTrace();
        }
    }

At some point we may find ourselves piddling around with images for creating splash screens, icons and web design.  Interesting little hint about what resizing algorithms you should use in your favourite graphics prog:

• When REDUCING a big image to a small image use BICUBIC
• When INCREASING a small image to a big image use BILINEAR

….I always forget this simple but useful information.

Huh?  Not C#!!! – What’s all this “Rant in C Sharp” business then!?  Well, sometimes you have to be flexible in your job – well, lets just say we should be ‘language ambivalent’.

This is a VERY simple attempt to show show how to create a web service in Eclipse using Axis.  There is also some client code to show how you would interact with that web service.  For some reason I had to delve into a bazillion websites and scour a million books before I could make some sort of sense of it all – so just so you don’t have the same trouble – I have decided to publish it (well actually, it’s so that I don’t forget either).

Little disclaimer – I’m not saying that this is difinitive, I may be missing something, but it seems to work for me just now, and I haven’t gone into all the ‘bells and whistles’ of web services.  At the moment I’m writing down everything I learn and hopefully help others by sharing the knowledge.

(Using Java 1.5)

Create Basic Web Service

1. Create new Dynamic Web Project.
2. Create new Java class (call it “DoesMagic”).
3. Add method like this (perhaps):

public class DoesMagic{
    public String doBasicStuff(String message)
    {
        return "This is your message: " + message;
    }
}

4. Right click on class you just made, New -> Other -> Web Services -> Web Service, you should get a form like the one below:

This will create all the necessary files to be able to publish your class as a web service.  If you want you can also create a client automatically by moving the slider – but what it generates may be hard to understand at first glance, so I have written a simple example of client code (see later on…).

5.  In order to run the web service – just,  Run as -> Run on Server.  Once the web service is running and alive on Tomcat – then we should be able to use it via some client code (see next bit).

Create Basic Web Service Client

Must create a project that has all the axis.jar type stuff in the WebContent folder – this can usually be made by generating a client application via the above wizard – you don’t have to use all the auto generated classes to access your web service, just do the following:

1.  Create a new Java Class – call it TestClient.

2.  Make it a main class, and enter the following code:

import javax.xml.namespace.QName;
import org.apache.axis.client.Call;
import org.apache.axis.client.Service;

public class TestClient {

public static void main(String [] args)
{
    try{
       String endpoint = "http://localhost:8080/TestWebService/services/DoesMagic";

       Service service = new Service();
       Call call = (Call) service.createCall();
       call.setTargetEndpointAddress( new java.net.URL(endpoint) );
       call.setOperationName( new QName("http://testPackage.fc.com", "doBasicStuff") );

       String ret = (String) call.invoke( new Object[] {"Hello World"} );
       System.out.println(ret);
       }
       catch(Exception e){
           System.err.println(e.toString());
       }
}
}

3.  Go to your web service project you made before and look at the source code for the wsdl file that has been created.  It’s in the folder WebContent -> wsdl.  Inside there you will find a wsdl that is the same name as your class.

4. You need to look at the wsdl and find the endpoint – which looks similar to:

"http://localhost:8080/TestWebService/services/DoesMagic"

and you need to get the namespace and the method name you want to invoke  (as shown above, should be in a very similar format).

5. In this case, when we get to the point that the call.invoke command is being issued it is casting the result to a String and we are sending in a String called “Hello World” – this should create a message in the console like “This is your message: Hello World”.

6. To test the class, just run the project as a Java Application and you should see the result in the Console printed out.

Conclusion

This is not indepth – this may not even be 100% correct, but it just gives you a taste of what can be achieved – it’s up to you now to read up more on Java Web Services.  Good luck !

PS – Take a sec just to vote whether this article helped you or not – see widget below.  If not, tell me what’t wrong with it and I’ll try and improve it.  I love feedback so I look forward to your comments!

]]> http://rantincsharp.wordpress.com/2008/10/14/a-simple-soap-web-service-example-in-eclipse-ganymede/feed/ 6 earnshaw webservice