1   package com.trendmicro.grid.acl.l0;
2   
3   import com.trendmicro.grid.acl.l0.datatypes.*;
4   import org.springframework.stereotype.Service;
5   
6   import javax.annotation.Resource;
7   import javax.ws.rs.*;
8   import java.util.List;
9   
10  /**
11   * Implements a REST styled interface on top of the SOAP api using JAX-RS
12   *
13   * @author juergen_kellerer, 2010-05-31
14   * @version 1.0
15   */
16  @Service
17  //@PublicRequestContext - Not required as injected instance is already wrapped by an AspectJ proxy.
18  @Path("/categories")
19  @Produces({"application/xml", "application/json"})
20  public class PublicCategoryRestService implements Level0RestService {
21  
22  	@Resource
23  	private PublicCategoryService categoryService;
24  
25  	/**
26  	 * Returns the names of available category views,
27  	 *
28  	 * @param locale           The locale (language & country) of the requester (views are regional!).
29  	 * @param targetIdentifier Optional identifier specifying the requesting target application type.
30  	 *                         Is set to "default" if left empty or if it is not existing.
31  	 * @return A list of available viewnames.
32  	 * @throws AuthenticationException In case of this service requires authentication and the current user session
33  	 *                                 is not authenticated or doesn't have the right to access the service.
34  	 * @RequiredRoles ROLE_RUN_CATEGORIZATION_QUERIES
35  	 */
36  	@GET
37  	@Path("/categoryViewNames/{locale}/{targetIdentifier}")
38  	public NameList getCategoryViewNames(
39  			@PathParam("locale") String locale,
40  			@PathParam("targetIdentifier") String targetIdentifier) throws AuthenticationException {
41  		List<String> names = categoryService.getCategoryViewNames(locale, targetIdentifier);
42  		if (names == null)
43  			return null;
44  		return new NameList(names);
45  	}
46  
47  	/**
48  	 * @param locale   The locale (language & country) of the requester.
49  	 * @param viewName The name of the view to return.
50  	 * @return The cateogry view for the given name or 'null' if not existing.
51  	 * @throws AuthenticationException In case of this service requires authentication and the current user session
52  	 *                                 is not authenticated or doesn't have the right to access the service.
53  	 * @RequiredRoles ROLE_RUN_CATEGORIZATION_QUERIES
54  	 */
55  	@GET
56  	@Path("/categoryView/{locale}/{viewName}")
57  	public CategoryView getCategoryView(
58  			@PathParam("locale") String locale,
59  			@PathParam("viewName") String viewName) throws AuthenticationException {
60  		return categoryService.getCategoryView(locale, viewName);
61  	}
62  
63  	/**
64  	 * Returns the plain category information (without any view or child relationship).
65  	 *
66  	 * @param locale       The locale (language & country) of the requester.
67  	 * @param categoryName The name of the category to return.
68  	 * @return The plain category (without any view or child relationship).
69  	 * @throws AuthenticationException In case of this service requires authentication and the current user session
70  	 *                                 is not authenticated or doesn't have the right to access the service.
71  	 * @RequiredRoles ROLE_RUN_CATEGORIZATION_QUERIES
72  	 */
73  	@GET
74  	@Path("/plainCategory/{locale}/{categoryName}")
75  	public Category getPlainCategory(
76  			@PathParam("locale") String locale,
77  			@PathParam("categoryName") String categoryName) throws AuthenticationException {
78  		return categoryService.getPlainCategory(locale, categoryName);
79  	}
80  
81  	/**
82  	 * Returns all plain categories (without any view or child relationship).
83  	 *
84  	 * @param locale The locale (language & country) of the requester.
85  	 * @return All plain categories (without any view or child relationship).
86  	 * @throws AuthenticationException In case of this service requires authentication and the current user session
87  	 *                                 is not authenticated or doesn't have the right to access the service.
88  	 * @RequiredRoles ROLE_RUN_CATEGORIZATION_QUERIES
89  	 */
90  	@GET
91  	@Path("/plainCategories/{locale}")
92  	public CategoryList getPlainCategories(
93  			@PathParam("locale") String locale) throws AuthenticationException {
94  		return new CategoryList(categoryService.getPlainCategories(locale));
95  	}
96  
97  	/**
98  	 * Returns the names of the categories that the given file belongs to.
99  	 *
100 	 * @param sha1OrMd5Hash the SHA1 or MD5 hash to test against categorization.
101 	 * @return the category names that reference this identifier.
102 	 * @throws AuthenticationException In case of this service requires authentication and the current user session
103 	 *                                 is not authenticated or doesn't have the right to access the service.
104 	 * @RequiredRoles ROLE_RUN_CATEGORIZATION_QUERIES, ROLE_RUN_COMPLEX_QUERIES
105 	 */
106 	@GET
107 	@Path("/referencingNamesOnFile/{sha1OrMd5}")
108 	public NameList getReferencingCategoryNamesOnFile(
109 			@PathParam("sha1OrMd5") String sha1OrMd5Hash) throws AuthenticationException {
110 		return categoryService.getReferencingCategoryNamesOnFile(new FileIdentifier(sha1OrMd5Hash));
111 	}
112 
113 	/**
114 	 * Returns the names of the categories that the given package file belongs to.
115 	 *
116 	 * @param sha1OrMd5Hash the SHA1 or MD5 hash to test against categorization.
117 	 * @return the category names that reference this identifier.
118 	 * @throws AuthenticationException In case of this service requires authentication and the current user session
119 	 *                                 is not authenticated or doesn't have the right to access the service.
120 	 * @RequiredRoles ROLE_RUN_CATEGORIZATION_QUERIES, ROLE_RUN_COMPLEX_QUERIES
121 	 */
122 	@GET
123 	@Path("/referencingNamesOnPackageById/{sha1OrMd5}")
124 	public NameList getReferencingCategoryNamesOnPackageById(
125 			@PathParam("sha1OrMd5") String sha1OrMd5Hash) throws AuthenticationException {
126 		return categoryService.getReferencingCategoryNamesOnPackageById(new FileIdentifier(sha1OrMd5Hash));
127 	}
128 
129 	/**
130 	 * Returns the names of the categories that the given package file belongs to.
131 	 *
132 	 * @param packageName the name of the package to test against categorization.
133 	 * @return the category names that reference this identifier.
134 	 * @throws AuthenticationException In case of this service requires authentication and the current user session
135 	 *                                 is not authenticated or doesn't have the right to access the service.
136 	 * @RequiredRoles ROLE_RUN_CATEGORIZATION_QUERIES, ROLE_RUN_COMPLEX_QUERIES
137 	 */
138 	@GET
139 	@Path("/referencingNamesOnPackage/{packageName}")
140 	public NameList getReferencingCategoryNamesOnPackageByName(
141 			@PathParam("packageName") String packageName) throws AuthenticationException {
142 		return categoryService.getReferencingCategoryNamesOnPackageByName(packageName);
143 	}
144 }