Fydji WS: Quick Start guide

About this document

This guide lets you quickly create and test a Fydji WS project. The QuickStart project described in this document may also be used as a template for your new Fydji WS projects.

Attention, this guide is written for Fydji WS version 2.0 or later.

Prerequisites

You need a text (or better, an XML) editor and Ant build tools in order to create Fydji WS Web Services.

For this guide we will use:

the Eclipse IDE to work with Fydji WS project;
the Tomcat servlet container to deploy and test Web Services.

In this document, we present an example of how to publish Web Services from SQL operations, so you should have a database and corresponding JDBC driver available too.

General usage principles

You use a Fydji WS project to create the Web Services in the following way:

You describe your services in a so called WSD files (Web Services Description). It is an XML file where you declare the list of operations to be to published, their input and output parameters, actions that must be executed when operations are invoked, and their result presentation. You also declare classes that you would like to be created to hold operations and their results.
You then execute Fydji WS project Ant tasks in order to generate all classes and resources described in WSD files. Ant tasks generate:
- a Java Web application that publishes Web Services;
- client classes that may be used to call services from a third party client application.

This document gives you a short overview of those principles.

Obtaining QuickStart project

A quick start project archive is published on SourceForge among the framework's latest version. You may find its reference on Fydji WS Web site http://www.fydji.org/projects/fydji-ws.

Preparing Eclipse

Once downloaded, you may import the QuickStart project it into your Eclipse workspace. It is a pre-configured Eclipse Java project including all necessary libraries and resources.

Fydji WS descriptions are given as XML files with extensions *.wsd and *.wsdgroup. Those extensions should be associated with an XML editor, if the one is available in your Eclipse installation. You do this trough the Eclipse General > Content Types and General > Editors > File Associations preferences.

Project structure

A Fydji WS project is a Java project with the following structure.

wsresources - it contains one or more .wsdgroup folders - Web Services Description groups. Each "group" includes one or more Web Services description files (.wsd files).
srcGen - this folder contains Java classes that are automatically generated from Web Services descriptions during project's build process. This folder must be declared as Java "source" folder.
dist - contains artifacts generated during project's build: classes to use in a client application (client folder), Web application publishing Web Services (server) and temporary generated resources (temp).
lib - includes various libraries. The Java libraries are placed in lib.java sub-folder. The libdef.properties file defines how those libraries are slit up between the client and the server during project's build.
docs - in this folder you can find some Fydji WS documentation references.
resources - some additional resources used by Fydji WS. In particular, the resources that will be integrated into the generated Web application during project's build (webapp folder).
The root folder (here FydjiWSQuickStart) contains Ant build files implementing project's compilation engine. The build.xml file contains "main" Ant tasks. The build.engine.xml file is used by build.xml to provide the concrete implementation of build tasks. This file might not be modified. The build process may be customized trough the build.properties file.

Configure the project

It is important to verify the Fydji WS project's configuration parameters placed in build.properties file. All parameters are documented so you should consult this file for more information.

By default, Fydji WS project uses Tomcat servlet container to deploy and test Web Services during its development process. All tasks relative to Tomcat instance management (deploy, startup, shutdown,...) are placed in build.tomcat.xml file.

If you effectively use Tomcat for Fydji WS Web Services development and test, you should check the fydji.tomcat.root parameter in build.properties file. If you don't use Tomcat, you may just comment this line in build.xml file to avoid errors during project build:

<import file="build.tomcat.xml"/>

Declaring Web Services

A Web Service comprises a set of operations. Several services may be put together into a Web Services group. A Fydji WS project may include one or more of those groups.

A Web Services description is given in an XML file with the .wsd extension. Each WSD description must belong to a Web Services group. A group is represented by a folder named GroupName.wsdgroup (the folder must have .wsdgroup extension). Each group must contain the index.wsdgroup file with a general description of declared Web Services.

All project's WSD groups must be placed in the wsresources folder which must be located on the project's classpath. Usually we place it in the src folder.

A Web Service and its operations are declared in a .wsd file heaving the following structure:

<webService> - the root element that contains the attribute name providing the Web Service name. The name must be unique among all services published by this project, independently from the group in which the service is declared. The name usually corresponds to the .wsd file name.
<description> - this section contains the Web Service description. It is integrated into generated service documentation.
<server> - this tag includes a <dataSource> element specifying the data source name on which this service operations are executed. This name may represent JDBC or LDAP connection. The concrete connection is obtained from application's context during its execution.
<client> - it declares the Java class that will be automatically generated and will include all declared operations. This class is used to invoke the Web Service operations from a Java client application. If necessary, this element may include declarations for other clients: JavaScript, PHP.
<operation> - it describes a particular operation. There will be methods created in <client> class with the name corresponding to the operation's name attribute. The <operation> tag must include the following nested tags:
- <description> - gives the operation's description to be integrated into generated documentation.
- <parameters> - contains the operation's input (<in>) and output (<out>) parameters.
- <action> - specifies the action to execute when this operation is called: a SQL query execution, a stored procedure call, a Java method invocation, an external application execution, a LDAP search operation call. The operation takes parameters defined in <in> tag and returns the result whose structure corresponds to <out> parameters.
- <result> - describes the representation of the result returned by the operation call on the client side. The possible (optional) representations are:
  - <xmlDocument> - gives the structure of the XML message returned to the client. The message will contain XML encoded operation result content.
  - <javaObject> - indicates that the result entities received in Java client application must be encapsulated into the given Java class objects. This class will be automatically generated.
  - <jsObject> - indicates that the result entities received in JavaScript client application must be encapsulated into the given JavaScript objects. This class will be automatically generated.
  - <phpObject> - indicates that the result entities received in PHP client applications must be encapsulated into the given PHP objects. This class will be automatically generated.

In the above description example, we declare a Web Service named "MyServices". We declare that this service's operations must be "placed" in the fydjiws.qstart.client.FydjiWSQSClient Java class. This class will be used to call the Web Services from a client application.

We declare an operation named "getMoviesByTitle performing movies search operation. It takes as a parameter the title of movie(s) to find. The operation corresponds to a SQL query that will be executed using a connection returned by the data source named "jdbc/QuickStart" (see the <server> element). We denote by "$0" the position where the input parameter value will be placed. Here "$0" stands for the first input parameter, "$1" - the second, and so on.

This operation returns the result composed from "title", "category", "release date", "budget" and "rating note". Columns selected by the SQL query conforms to this declaration. We also declare that on the client side, each result entity (selected "record") will be encapsulated into fydjiws.qstart.client.vo.Movie object. This class will have the "getters" and "setters" corresponding to result's fields (output parameters): "title", "category", etc...

One may continue to add more operations declaring different SQL "actions" and returning different results. They all will use connections to the same "jdbc/QuickStart" data source referenced. The declared Java classes are automatically generated and documented during the Fydji WS project's build.

Building the project

We use Ant tasks defined in build.xml to build a Fydji WS project. This file is located in project's root folder.

In the Eclipse IDE, you may open this file in the Ant view. It this view is not yet present in your perspective, you may open it trough the Window > Show View menu.

The build process follows those principal steps:

Execute the 20_GenerateFiles task. It generates classes from WSD descriptions, creates the generated services HTML documentation and creates Web Services descriptions for Axis engine.
Execute the 30_BuildApp task. It creates a Web application that publishes the declared Web Services. It also creates client bundles with resources to be included in a client applications. A separate bundle is generated for each declared client: Java, JavaScript, PHP.
Refresh the project in the workspace in order to make visible to Eclipse all changes that have been performed on the project.

The project's build artifacts are placed in its dist folder. There are two main sub-folders:

client - this folder, and in particular its java sub-folder contains everything we need to put into the client application in order to call Web Services. Its lib folder contains third party Java libraries. Generated classes are placed in the main .jar file (here FydjiWSQuickStartClient.jar).
server - it contains a ready to use Web application. It may be installed in an application server or a servlet container.

Deploying Web Services

The Web application do be deployed on an application server is located in projects dist/server/webapp folder. To deploy this application:

Install it into your application server. If you use Tomcat, you may place it in its webapps folder.
Add the data source definition to this application context. It must have the same name as the one declared in corresponding Web Services description file (.wsd file), its <server> tag.

If you use Tomcat version 5.5 or later, you may declare the data source in an META-INF/context.xml file. Its example is given in project's resources/webapp/META-INF folder. If this file is present in resources folder during project's build, it is automatically included in built application.

Once application deployed, you may open your Web browser and point it to the application's page. If this guide's application is deployed on a Tomcat server with default configuration, the URL should be http://localhost:8080/FydjiWSQuickStart/. You should get access to Web Services generated documentation which includes published Web Services, their operations, input and output parameters description. In also includes an example of code that must be used to call Web Services from client applications.

Calling Web Services

In order to call Web Services, you must include in your target Java project all resources available in Fydji WS project's dist/client/java folder:

Add the main java library with generated client classes. In this example, it is the FydjiWSQuickStartClient.jar archive.
Add to the target project's classpath all libraries available in lib sub-folder.

You can then write a Java class which creates Web Services client instance and calls the published operations. In this guide's example, the Web Service client class is FydjiWSQSClient.

The quick start project includes an example of code that may be used to call Fydji WS Web Service in its org.fydji.qstart.test.FydjiWSQuickstartTest class.

Starting a new project from the QuickStart project

The QuickStart project may be used as a template to start a new Fydji WS project. You may proceed in the following way:

Make a copy of QuickStart project:
- Import the existing QuickStart project into your workspace. Just remember, this is a Java project. Open the project in the Package Explorer view.
- Rename the project. You may select the project's root (here FydjiWSQuickStart) then go to the menu Refactor > Rename. Lets suppose that we name the new project MyProject.
Change the project's name in build files:
- in the build.properties file, change the fydji.webapp.name parameter's value to "MyProject". You may also check the other parameters and in particular the Tomcat installation path (fydji.tomcat.root).
- In the build.xml file, change its name attribute's value to "MyProject". This is optional operation but it lets more easily distinguish the new project from existing projects when the build.xml file is opened in the Ant view.
Change the Web Services definitions. They are located in the src/wsresources/QStartServices.wsdgroup folder:
- Rename the QStartServices.wsdgroup folder by giving it the name of the service group that you want to create. The name's choice is not very important, but be sure to keep the ".wsdgroup" extension.
- Open the index.wsdgroup file and change the service's description. Also, change the application's name in the default URL. It must correspond to the one given by fydji.webapp.name in build.properties file.
- Rename the file QStartService.wsd by giving it the name of the Web Service that you want to create. It is important to keep the ".wsd" extension. You may also add other services definitions by placing them in separate .wsd files.
- Open the file with an XML (or text) editor and change the name attribute in <webService> tag. This will be the name used for published Web Service. In general, it is the same name as the .wsd file's name.
- Change the service description, client classes declarations, add or modify the operations' definitions.
If you publish your Web Services from a database, check the data source definition in the resources/webapp/META-INF/context.xml file. Delete this file if you don't use data source or if it is defined otherwise. You may also put into webapp folder other resources to be integrated into the generated Web application.

Once your project is ready, open its build.xml file in the Ant view and use included tasks to build the project.

What's next?

This document gave you a very basic presentation of how the Web Services may be published with Fydji WS framework. There is much more to learn about this framework:

Mapping services' to stored procedures.
Mapping services' to Java Methods.
Mapping services' to executables (applications, shell scripts) and parsing their execution result.
Mapping services' to LDAP search operation and defining connections to LDAP data sources.
Customizing the client and server side Java classes.
Creating and consuming the services for JavaScript/AJAX client.
Creating and consuming the services for PHP client.
Publishing REST style services.
Transforming your services' result with an XSL style sheet.

Those and other points are covered in a separate documentation. For more information, you may contact Fydji WS developers following the contact references on Fydji.org Web site.