The @javax.ws.rs.Path annotation indicates the URI path to which a resource class or a class method must respond. The value that you specify for the @Path annotation is relative to the URI of the server where the REST resource is hosted. This annotation can be applied at both the class and method levels.

Specifying the @Path annotation on a resource class

The following code snippet illustrates how you can make a POJO class respond to a URI path template containing the /departments path fragment:

import javax.ws.rs.Path; 
 
@Path("departments") 
public class DepartmentService { 
  //Rest of the code goes here 
} 

The /department path fragment that you see in this example is relative to the base path in the URI. The base path typically takes the http://host:port/<context-root>/<application-path> URI pattern. You will learn how to set an application path for a JAX-RS application in the Specifying application path section, which comes later in this chapter.

Specifying the @Path annotation on a resource class method

The following code snippet shows how you can specify @Path on a method in a REST resource class. Note that for an annotated method, the base URI is the effective URI of the containing class. For instance, you will use the URI of the /departments/count form to invoke the getTotalDepartments() method defined in the DepartmentService class, where departments is the @Path annotation set on the class:

import javax.ws.rs.GET; 
import javax.ws.rs.Path; 
import javax.ws.rs.Produces; 
@Path("departments") 
public class DepartmentService { 
    @GET 
    @Path("count") 
    @Produces("text/plain") 
    public Integer getTotalDepartments() { 
        return findTotalRecordCount(); 
    } 
  //Rest of the code goes here 
} 

Specifying variables in the URI path template

Very often, a client will want to retrieve the data for a specific object by passing the desired parameter to the server. JAX-RS allows you to do this via the URI path variables, as discussed here.

The URI path template allows you to define the variables that appear as placeholders in the URI. These variables will be replaced at runtime with the values set by the client.

The following example illustrates the use of the path variable to request for a specific department resource. The URI path template looks like this: /departments/{id}. At runtime, the client can pass an appropriate value for the id parameter to get the desired resource from the server. For instance, the URI path of the /departments/10 format returns the IT department details to the caller.

The following code snippet illustrates how you can pass the department ID as a path variable for deleting a specific department record. The path URI looks like /departments/10:

import javax.ws.rs.Path; 
import javax.ws.rs.DELETE; 
 
@Path("departments") 
public class DepartmentService { 
 
  @DELETE 
  @Path("{id}") 
  public void removeDepartment(@PathParam("id")  
  short id) { 
    removeDepartmentEntity(id); 
  } 
  //Other methods removed for brevity 
} 

In the preceding code snippet, the @PathParam annotation is used for copying the value of the path variable to the method parameter. We will discuss this in detail in the Annotations for accessing request parameters section.

Restricting values for path variables with regular expressions

JAX-RS lets you use regular expressions in the URI path template for restricting the values set for the path variables at runtime by the client. By default, the JAX-RS runtime ensures that all the URI variables match the following regular expression: [^/]+?. The default regular expression allows the path variable to take any character except the forward slash (/). What if you want to override this default regular expression imposed on the path variable values? Good news is that JAX-RS lets you specify your own regular expression for the path variables. For example, you can set the regular expression as given in the following code snippet in order to ensure that the department name variable present in the URI path consists only of lowercase and uppercase alphanumeric characters:

@DELETE 
@Path("{name: [a-zA-Z][a-zA-Z_0-9]}") 
public void removeDepartmentByName(@PathParam("name")  
  String deptName) { 
    //Method implementation goes here 
} 

If the path variable does not match the regular expression set of the resource class or method, the system reports the status back to the caller with an appropriate HTTP status code, such as 404 Not Found, which tells the caller that the requested resource could not be found at the moment.