JBoss.orgCommunity Documentation

Chapter 6. Sample Web Service wizards

6.1. Sample Web Service
6.1.1. Generation
6.1.2. Deployment
6.2. Sample RESTful Web Service

JBoss Tools includes wizards for the creation of sample web services. These include:

These wizards are used within a Dynamic Web project. A dynamic web project can be created by following the steps in Creating a dynamic web project.

Procedure 6.1. Creating a dynamic web project

  1. Access the New Project Dialog

    Select File → New → Project

    Result:

    The New Project screen displays.

  2. Define the Project Type

    1. Click the Dynamic Web Project label by expanding the Web folder.

    2. Click the Next button to proceed.

    Result:

    The New Dynamic Web Project screen displays.

    Dynamic Web Project Attributes

    [    D]

    Figure 6.1. Dynamic Web Project Attributes


  3. Define the Project Attributes

    Define the Dynamic Web Project attributes according to the options displayed in Table 6.1, “New Dynamic Web Project”

    Table 6.1. New Dynamic Web Project

    FieldMandatoryInstructionDescription
    Project nameyesEnter the project name.The project name can be any name defined by the user.
    Project locationyesClick the Use default location checkbox to define the project location as the Eclipse workspace or define a custom path in the Location field.The default location corresponds to the Eclipse workspace.
    Target runtimenoSelect a pre-configured runtime from the available options or configure a new runtime environment.

    The target runtime defines the server to which the application will be deployed.

    Dynamic web module versionyesSelect the required web module version.

    This option adds support for the Java Servlet API with module versions corresponding to J2EE levels as listed in Table 6.2, “New Dynamic Project - Dynamic web module version”.

    ConfigurationyesSelect the project configuration from the available options.

    The project can be based on either a custom or a set of pre-defined configurations as described in Table 6.3, “New Dynamic Project - Configuration”.

    EAR membershipnoAdd the project to an existing EAR project.

    The project can be added to an existing EAR project by selecting the checkbox. Once checked, a new EAR project can be defined by clicking the New Project button.

    Working setsnoAdd the project to an existing working set.

    A working set provides the ability to group projects or project attributes in a customized way to improve access. A new working set can be defined once the Select button has been clicked.


    Table 6.2. New Dynamic Project - Dynamic web module version

    OptionDescription
    2.2This web module version corresponds to the J2EE 1.2 implementation.
    2.3This web module version corresponds to the J2EE 1.3 implementation.
    2.4This web module version corresponds to the J2EE 1.4 implementation.
    2.5This web module version corresponds to the JEE 5 implementation.

    Table 6.3. New Dynamic Project - Configuration

    OptionDescription
    <custom>Choosing from one of the pre-defined configurations will minimise the effort required to set up the project.
    BIRT Charting Web ProjectA project with the BIRT Charting Runtime Component.
    BIRT Charting Web ProjectA project with the BIRT Reporting Runtime Component.
    CXF Web Services Project v2.5Configures a project with CXF using Web Module v2.5 and Java v5.0.
    Default Configuration for JBoss 5.0 RuntimeThis option is a suitable starting point. Additional facets can be installed later to add new functionality.
    Dynamic Web Project with Seam 1.2Configures a project to use Seam v1.2.
    Dynamic Web Project with Seam 2.0Configures a project to use Seam v2.0.
    Dynamic Web Project with Seam 2.1Configures a project to use Seam v2.1.
    Dynamic Web Project with Seam 2.2Configures a project to use Seam v2.2.
    JBoss WS Web Service Project v3.0Configures a project with JBossWS using Web Module v2.5 and Java v5.0.
    JavaServer Faces v1.2 ProjectConfigures a project to use JSF v1.2.
    Minimal ConfigurationThe minimum required facets are installed. Additional facets can be chosen later to add functionality to the project.

  4. Access the Java sub-dialog

    Click Next to proceed.

    Result:

    The New Dynamic Web Project - Java dialog displays.

  5. Define the source and output folders

    Define the Dynamic Web Project source and output folders by adding or editing folders as required.

  6. Access the Web Module sub-dialog

    Click Next to proceed.

    Result:

    The New Dynamic Web Project - Web Module dialog displays.

    New Dynamic Web Project - Web Module

    [    D]

    Figure 6.2. New Dynamic Web Project - Web Module


  7. Enter the web module settings

    Define the settings as listed in Table 6.4, “New Dynamic Web Project - Web Module” including the root folder for path names in the web project context and the name of the web content directory.

    Table 6.4. New Dynamic Web Project - Web Module

    FieldMandatoryInstructionDescription
    Context rootyesEnter the context root for the project.The context root identifies a web application to the server and which URLs to delegate to the application.
    Content directoryyesEnter the directory name for the web content.Web resources such as html, jsp files and graphic files will be written to the specified content directory.
    Generate web.xml deployment descriptornoCheck this box to generate a deployment descriptor for the project.URL to servlet mappings and servlet authentication details are written to the deployment descriptor enabling the web server to serve requests.

  8. Open the Java EE perspective.

    1. Click the Finish button to complete the project setup.

      Result:

      If not already set, a dialog will appear prompting the user to open the relevant perspective.

    2. Click the Yes button to display the Java EE perspective.

      Result:

      The project is configured and the Java EE perspective is displayed.

6.1. Sample Web Service

These sections describe how to generate and deploy a sample web service.

A sample web service can be created by using the Create a Sample Web Service wizard as described in Generate a sample web service

Procedure 6.2. Generate a sample web service

  1. Access the New - Select a wizard dialog

    1. Right click on the project name in the Project Explorer view.

    2. Select New → Other.

    3. Click the Create a Sample Web Service label by expanding the Web Services folder.

    Result:

    The New - Select a wizard dialog displays with the selected wizard type highlighted.

  2. Access the Generate a Sample Web Service dialog

    Click the Next button to proceed.

    Result:

    The Generate a Sample Web Service - Project and Web Service Name dialog displays.

    Generate a Sample Web Service - Project and Web Service Name

    [    D]

    Figure 6.3. Generate a Sample Web Service - Project and Web Service Name


  3. Define the service attributes

    Define the project, web service, package and class names according to the options displayed in Table 6.5, “Project and Web Service Name”

    Table 6.5. Project and Web Service Name

    Dialog groupFieldMandatoryInstructionDescription
    Dynamic Web Project yesEnter the project name.The project name will default to the highlighted project in the Project Explorer. A different project can be selected from the list or entered directly in the editable drop-down list.
    Web ServiceNameyesEnter the name for the web service.The web service name will be the url for the service as mapped in the deployment descriptor (web.xml).
    Sample Web Service ClassPackageyesEnter the package for the web service servlet.The default package for the sample web service will be displayed.
     ClassyesEnter the name of the web service servlet.The default class name will correspond to the default web service name resulting in an equivalent url to servlet name mapping in the deployment descriptor (web.xml).

  4. Generate the web service

    Click the Finish button to complete the web service setup.

    Result:

    The web service classes will be generated and the web.xml file updated with the deployment details.

  5. Browse the HelloWorld.java class

    Double click the HelloWorld.java class and note the annotated class name and method. These annotations identify the web service entities to the server.

    web.xml

    [    D]

    Figure 6.4. web.xml


  6. Browse the web.xml deployment decriptor

    Double click the web.xml file and note the servlet mapping as defined in Figure 6.3, “Generate a Sample Web Service - Project and Web Service Name”. Note also that:

    • the main servlet for the application is org.jboss.samples.webservices.HelloWorld which is given the custom name HelloWorld; and

    • the main servlet is mapped to the particular url /HelloWorld [1].

    web.xml

    [    D]

    Figure 6.5. web.xml


    Upon start up, the server will write a WSDL file to the server-profile/data/wsdl/ directory and the WSDL can be accessed with http://localhost:8080/ProjectName/[1]?WSDL or, http://localhost:8080/WebServiceSample/HelloWorld?WSDL.

Once created, the sample web service can be deployed to the target runtime as described in Export the project as a Web Archive (WAR).

Procedure 6.3. Export the project as a Web Archive (WAR)

  1. Access the Export dialog

    1. Right click on the project name in the Project Explorer view.

    2. Select Export → WAR file.

    Result:

    The Export- WAR Export dialog displays with the selected web project highlighted.

    Export - WAR Export dialog

    [    D]

    Figure 6.6. Export - WAR Export dialog


  2. Complete the export dialog

    Define the WAR file attributes as described in Table 6.6, “Export - War Export”

    Table 6.6. Export - War Export

    FieldMandatoryInstructionDescription
    Web projectyesEnter the web project name.The project name will default to the highlighted project in the Project Explorer. A different project can be selected from the list or entered directly in the editable drop-down list.
    DestinationyesEnter or browse to the destination.Set the destination as the build folder to store the WAR file within the project. Alternatively, deploy the project directly to the deploy directory of the target server profile.
    Optimize for a specific server runtimenoSelect this box to optimize the WAR file for deployment to the targeted runtime.The list of available runtimes will be those configured during the project set-up or by selecting File → New → Server.

  3. Deploy the application

    Copy the file to the deploy directory of the required target server profile, such as the all profile. Note that the WAR file destination may have already been set as the deploy directory in Step 2.

6.2. Sample RESTful Web Service

A sample Restful web service can be generated by following the steps outlined in Generate a sample RESTful web service.

Procedure 6.4. Generate a sample RESTful web service

Target runtime must have RESTEasy installed

The sample RESTful web service will not work unless it is deployed to a server with RESTEasy installed.

  1. Access the New - Select a wizard dialog

    1. Right click on the project name in the Project Explorer view.

    2. Select New → Other.

    3. Click the Create a Sample RESTful Web Service label by expanding the Web Services folder.

    Result:

    The New - Select a wizard dialog displays with the selected wizard type highlighted.

  2. Access the Generate a Sample RESTful Web Service dialog

    Click the Next button to proceed.

    Result:

    The Generate a Sample RESTful Web Service - Project and Web Service Name dialog displays.

    Generate a Sample RESTful Web Service - Project and Web Service Name

    [    D]

    Figure 6.7. Generate a Sample RESTful Web Service - Project and Web Service Name


  3. Define the service attributes

    Define the project, web service, package and class names according to the options displayed in Table 6.7, “Project and Web Service Name”

    Table 6.7. Project and Web Service Name

    Dialog groupFieldMandatoryInstructionDescription
    Dynamic Web Project yesEnter the project name.The project name will default to the highlighted project in the Project Explorer. A different project can be selected from the list or entered directly in the editable drop-down list.
    Web ServiceNameyesEnter the name for the web service.The web service name will be the url for the service as mapped in the deployment descriptor (web.xml).
     Update web.xmlnoCheck this box to add the service to the deployment descriptor.This option is checked by default and may be unchecked when deploying to JBoss AS 6.0 or RESTEasy 2.0 servers. Service information is not required in the deployment descriptor for these servers.
    Sample Web Service ClassPackageyesEnter the package for the web service class.The default package for the sample web service will be displayed.
     ClassyesEnter the name of the web service class containing the JAX-RS annotated path. This class defines the path to the web service and is referenced in the Application Class Name. The Application Class Name is declared in the deployment descriptor providing indirect access to the annotated path.
     Application Class NameyesEnter the name of the Application Class Name. The Application Class Name constructor instantiates objects of the web service class containing the JAX-RS annotated path, GET and POST methods. It serves as a single point of access to the application for the web server.

  4. Generate the web service

    Click the Finish button to complete the web service setup.

    Result:

    The web service classes will be generated and the web.xml file updated with the deployment details.

  5. Browse the MyRESTApplication.java class

    Double click the MyRESTApplication.java class and note the constructor instantiating objects of type HelloWorldResource. The relevance of this will be discussed shortly.

    Application Class - MyRESTApplication.java

    [    D]

    Figure 6.8. Application Class - MyRESTApplication.java


  6. Browse the HelloWorldResource.java class

    Double click the HelloWorldResource.java class and note the JAX-RS annotated path and the annotated GET method.

    HelloWorldResource.java

    [    D]

    Figure 6.9. HelloWorldResource.java


  7. Browse the web.xml deployment descriptor

    Double click the web.xml file and note the jax.ws.rs.Application parameter mapped to the Application class. Note also that:

    • the main servlet for the application is org.jboss.resteasy.plugins.server.servlet.HttpServletDispatcher which is given the custom name Resteasy; and

    • the main servlet is not mapped to a particular url as indicated by /*.

    The url for sending GET requests can be resolved as follows:

    1. Identify the Application Class as defined in the deployment descriptor.

    2. Note the object type instantiated in the Application class and added to the singleton set: HelloWorldResource.

    3. Note the JAX-RS annotated path declared in the corresponding HelloWorldResource class: @Path("/MyRESTApplication") [1].

    web.xml

    [    D]

    Figure 6.10. web.xml


    The url for sending GET requests is therefore http://localhost:8080/ProjectName/[1] or, http://localhost:8080/RestfulSample/MyRESTApplication.