You can configure Java™ API
for RESTful Web Services (JAX-RS) applications in multiple ways depending
on your needs. To take advantage of the Java Platform,
Enterprise Edition (Java EE)
6 functionality, you can use the annotation scanning capabilities.
By using annotation scanning, you can omit a JAX-RS javax.ws.rs.core.Application
subclass or have a minimally defined javax.ws.rs.core.Application
subclass.
About this task
The JAX-RS 1.1 specification supports several new ways
to configure a JAX-RS application. You can use the built-in annotation
scanning to help automatically configure the application. You can
optionally add javax.ws.rs.core.Application subclasses to your application
and then add the URL patterns required using either the javax.ws.rs.ApplicationPath
annotation or a web.xml servlet definition. When using the IBM® JAX-RS implementation, you do
not have to specify the servlet class implementation because it is
automatically added to the configuration of the web module by the
time the JAX-RS application is started.
When using a web.xml
file, you must use a Java Servlet
3.0 web.xml file.
Procedure
- Configure the JAX-RS application with only one JAX-RS default
application in the web.xml file.
Use this method if you
only need one JAX-RS application and all resource classes are located
after a single URL pattern. You can also specify security constraints
with this method, if needed.
- Add all of your JAX-RS resource and provider classes
to the WEB-INF/classes or WEB-INF/lib directory for your web application.
You do not need to add a javax.ws.rs.core.Application
subclass to your web application.
- In your web.xml file, add a servlet definition with
javax.ws.rs.core.Application as the servlet name.
You do
not need to add a servlet-class. You must add a servlet URL pattern
to the web.xml file. The application server runtime environment adds
the specific IBM JAX-RS implementation
to the configuration of the web module by the time the JAX-RS application
is started; for example:
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_3_0.xsd"
version="3.0">
<servlet>
<servlet-name>javax.ws.rs.core.Application</servlet-name>
</servlet>
<servlet-mapping>
<servlet-name>javax.ws.rs.core.Application</servlet-name>
<url-pattern>/rest/*</url-pattern>
</servlet-mapping>
</web-app>
The JAX-RS resources are now available at
a URL such as:
http://{hostname}:{port}/{context_root_of_Web_ module}/{value_of_Web.xml_URL_pattern}/{value_of_@javax.ws.rs.Path}
- Configure the JAX-RS application using the javax.ws.rs.core.Application
subclass and the web.xml file.
Use this method if you
need multiple JAX-RS applications or require only specific resources
in certain JAX-RS applications with specific URL patterns. You can
also specify security constraints with this method, if needed.
- Create a javax.ws.rs.core.Application subclass.
In your javax.ws.rs.core.Application subclass getClasses() or
getSingletons() methods, return the relevant JAX-RS resources and
providers. If you return empty sets in both the getClasses() and
getSingletons() methods, all the JAX-RS resource and provider classes
that are found in the application are added to the JAX-RS application
subclass; for example:
package com.example;
public class MyApplication extends javax.ws.rs.core.Application {
}
This example uses the default implementations of javax.ws.rs.core.Application
subclass getClasses() and getSingletons() methods that return empty
sets. Therefore, all relevant JAX-RS classes are assumed to be returned
by the javax.ws.rs.core.Application subclass.
- Add the javax.ws.rs.core.Application subclass to your
web application.
- Add a partial servlet definition in the web.xml file.
The servlet name is the full name of the javax.ws.rs.core.Application
subclass. Do not define the servlet-class. You must add a servlet
URL pattern to the web.xml file. The application server runtime environment
adds the specific IBM JAX-RS
implementation to the configuration of the web module by the time
the JAX-RS application is started; for example:
<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="https://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee
http://java.sun.com/xml/ns/j2ee/web-app_3_0.xsd"
version="3.0">
<servlet>
<servlet-name>com.example.MyApplication</servlet-name>
</servlet>
<servlet-mapping>
<servlet-name>com.example.MyApplication</servlet-name>
<url-pattern>/rest/*</url-pattern>
</servlet-mapping>
</web-app>
The JAX-RS resources are now available at
a URL such as:
http://{hostname}:{port}/{context_root_of_Web_ module}/{value_of_Web.xml_URL_pattern_for_Application_subclass}/{value_of_@javax.ws.rs.Path}
- Configure the JAX-RS application without a web.xml file.
Use this method if you do not want to use a web.xml file. When
you use this method, you cannot specify security constraints. To specify
security constraints, you must use a web.xml file.
- Create a javax.ws.rs.core.Application subclass.
In your javax.ws.rs.core.Application subclass getClasses() or
getSingletons() methods, return the relevant JAX-RS resources and
providers. If you return empty sets in both the getClasses() and
getSingletons() methods, all the JAX-RS resource and provider classes
that are found in the application are added to the JAX-RS application
subclass; for example:
package com.example;
public class MyApplication extends javax.ws.rs.core.Application {
}
This example uses the default implementations of javax.ws.rs.core.Application
subclass getClasses() and getSingletons() methods that return empty
sets. Therefore, all relevant JAX-RS classes are assumed to be returned
by the javax.ws.rs.core.Application subclass.
- Add a javax.ws.rs.ApplicationPath annotation to the
javax.ws.rs.core.Application subclass.
The ApplicationPath
annotation is supported with the JAX-RS 1.1 specification. The value
of the ApplicationPath annotation is used as the servlet URL pattern
which is equivalent to the servlet URL pattern in the web.xml file;
for example:
package com.example;
@javax.ws.rs.ApplicationPath("rest")
public class MyApplication extends javax.ws.rs.core.Application {
}
- Add the javax.ws.rs.core.Application subclass to your
web application.
When the application is started, the resources
are available at the following URL:
http://{hostname}:{port}/{context_root_of_Web_ module}/{value_of_@javax.ws.rs.ApplicationPath}}/{value_of_@javax.ws.rs.Path}
Results
You have configured your JAX-RS application using JAX-RS 1.1
supported methods by taking advantage of annotation scanning to help
automatically configure the application.