| Open Source by Fylab |
Table of Contents
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 1.5 or later. On Fydji WS Web site, you may find the references to an Eclipse plug-in used to create and manage projects for the Fydji WS versions prior to 1.0. This plug-in is not compatible with the project presented in this document. At the writing of this guide, there is no plug-in version available for 1.5 version.
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 a Fydji WS project;
the Tomcat servlet container to deploy and test Web Services.
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, the actions that must be executed when operations are invoked, and their result structure. You also declare classes that you would like to be created to hold operations and their results.
You then execute project's Ant tasks in order to generate all classes and resources described in WSD files. The Ant tasks generate:
a Java Web application that publishes the Web Services;
client classes that may be used to call the services from a third party client application.
This document gives you a short overview of those principles.
A quick start project archive is published on the SourceForge among the framework's latest version. You may find its reference on Fydji WS Web site http://www.fydji.org/en/products/fydji-ws.
Once downloaded, you may just unzip the QuickStart project archive and open or import it into your Eclipse workspace. It is a pre-configured Eclipse Java project including all necessary libraries and resources.
Fydji WS descriptions are given in 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.
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 the Java
classes that are automatically generated from Web Services
descriptions during the project's build process. This folder must
be declared as a Java "source" folder.
dist - contains artifacts generated during
the project's build: the 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.
docs - in this folder you can find some
Fydji WS documentation, including this guide.
resources - some additional resources
used by Fydji WS.
Ant build files forms the Fydji WS projects' compilation engine.
The build.xml file contains "public"
Ant tasks. The build.internal.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.user.properties file.
It is important to verify the Fydji WS project's configuration
parameters placed in build.user.properties file.
All parameters are documented so you should consult this file for more
information.
One of the important parameters is fydji.tomcat.root which
gives the path to the folder where your Tomcat is installed. The built
Web Services are independent from Tomcat. However, the project build
tasks makes reference to some Tomcat resources during the services
build process.
A Web Service comprises a set of operations. Several services may be put together in 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 they are declared.
The name usually corresponds to the .wsd
file name.
<description> - this section describes the
Web Service. The description is included in generated services
documentation.
<server> - this tag contains the elements
specifying the Java class that will publish the Web Service. This
tag also includes a <dataSource> element
specifying the data source name on which the service operations
are executed.
<client> - it describes the Java class
that will be used to invoke the declared Web Services from a client
application.
<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.
<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, a stored procedure,
a Java method. The operation takes the parameters defined in
<in> tag and returns the result whose
structure corresponds to the <out>
parameters.
<result> - describes the representation of
the result returned by the operation call on the client side.
The possible presentations are:
- <xmlDocument> - gives the structure
of the XML document returned to the client. This is the mandatory
tag in result's description.
- <javaObject> - indicates that on the
client, the result may also be encapsulated into the given Java
class objects.
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 the movie(s)
to find. The operation corresponds to an SQL query that will be executed
on the data source named "jdbc/QuickStart" (see the <server> tag).
We denote by "$0" the position where the input parameter's value will
be placed. Here "$0" stands for the first parameter, "$1" - second,
and so on.
This operation returns the result composed from "title", "category",
"release date", "budget" and "rating note". The SQL query's result
conforms to this declaration. We also declare that on the client side,
the result will be encapsulated into the fydjiws.qstart.client.vo.Movie
objects. This class will have the "getters" and "setters" corresponding
to result's fields: "title", "category", etc...
One may continue to add more operations declaring different SQL "actions" and returning different results. The declared Java classes may not exist. They are automatically generated and documented during the Fydji WS project's build.
We use the Ant tasks to build a Fydji WS project. Each project includes
the build.xml located at its root.
In the Eclipse IDE, you should 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 will generate declared classes from WSD descriptions, create the HTML documentation for created services and Web Services descriptions for Axis engine.
Execute the 30_BuildApp task. It will create a Web application that publishes the declared Web Services and create a client bundle with resources to be included in a client application.
Refresh the project in the workspace in order to make visible to the 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 the Web Services.
Its lib folder contains third party Java
libraries. The generated classes are placed in the main
.jar file (here FydjiWSQuickStart15Client.jar).
The src folder has the Web Services descriptions
that must also be present in client's classpath.
server - it contains a ready to use Web
application. It may be installed in an application server or
servlet container.
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 that declared in corresponding Web
Services definition file (.wsd file), the
<server> tag.
If you use Tomcat version 5.5 or later, you may also declare the
data source in an context.xml file that must be
placed in Web applications META-INF sub-folder.
An example of this file is given in project's resources
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://127.0.0.1:8080/FydjiWSQuickStart15/.
You should get access to Web Services online documentation.
In order to call Web Services, you include in your target Java project
the resources available in Fydji WS project's dist/client/java
folder:
Add to the target project's classpath all libraries available in
lib sub-folder. You must also add the library
with generated client classes. In this example, it is the
FydjiWSQuickStart15.jar archive.
Place the wsresources folder in your application
classpath (it is located in dist/client/java/src).
Usually, we place that folder in project's src
folder. It is important to keep wsresources
folder in an uncompressed state (do not put it in a .jar
archive).
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.
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 FydjiWSQuickStart15) 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.user.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 the
build.user.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, server and 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 context.xml file included the
project's resources sub-folder. Delete this file
if you don't use data source or if it is defined otherwise.
Once your project is ready, open its build.xml
file in the Ant view and use included tasks to build
the project.
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' operations to stored procedures.
Mapping services' operations to Java Methods.
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 at
<info@fylab.fr>.
Copyright © 2004-2007 Fylab