1   package com.trendmicro.grid.acl.l0;
2   
3   import com.trendmicro.grid.acl.ProtectedRequestContext;
4   import com.trendmicro.grid.acl.RequiredRoles;
5   import com.trendmicro.grid.acl.l0.datatypes.FileIdentifier;
6   import com.trendmicro.grid.acl.l0.datatypes.PackageDetails;
7   import com.trendmicro.grid.acl.l0.datatypes.PackageFamily;
8   import com.trendmicro.grid.acl.l0.datatypes.Vendor;
9   
10  import javax.jws.WebMethod;
11  import javax.jws.WebParam;
12  import javax.jws.WebResult;
13  import javax.jws.WebService;
14  import javax.servlet.annotation.WebServlet;
15  import javax.xml.ws.ResponseWrapper;
16  import java.util.Collection;
17  
18  import static com.trendmicro.grid.acl.l0.KnownRoles.ROLE_ACCESS_DETAILS;
19  import static com.trendmicro.grid.acl.l0.KnownRoles.ROLE_ACCESS_PROTECTED_SERVICES;
20  import static com.trendmicro.grid.acl.l0.KnownRoles.ROLE_RUN_PACKAGE_QUERIES;
21  
22  /**
23   * Defines package related web services, that may be used inside the TM network.
24   *
25   * @author Juergen_Kellerer, 2010-04-29
26   * @version 1.0
27   */
28  @ProtectedRequestContext
29  @WebServlet("/ws/level-0/internal/packages")
30  @WebService(targetNamespace = Level0Constants.NAMESPACE)
31  public interface PackageService extends PublicPackageService {
32  	/**
33  	 * Returns the vendor information for the given vendor name.
34  	 *
35  	 * @param name the name of the vendor to return.
36  	 * @return the vendor information for the given vendor name.
37  	 * @throws AuthenticationException In case of this service requires authentication and the current user session
38  	 *                                 is not authenticated or doesn't have the right to access the service.
39  	 */
40  	@WebMethod
41  	@WebResult(name = "vendor")
42  	@RequiredRoles({ROLE_RUN_PACKAGE_QUERIES, ROLE_ACCESS_DETAILS, ROLE_ACCESS_PROTECTED_SERVICES})
43  	Vendor getVendor(@WebParam(name = "name") String name) throws AuthenticationException;
44  
45  	/**
46  	 * Returns the package family on the given basename.
47  	 *
48  	 * @param basename the name of the package family.
49  	 * @return the package family on the given basename.
50  	 * @throws AuthenticationException In case of this service requires authentication and the current user session
51  	 *                                 is not authenticated or doesn't have the right to access the service.
52  	 */
53  	@WebMethod
54  	@WebResult(name = "packageFamily")
55  	@RequiredRoles({ROLE_RUN_PACKAGE_QUERIES, ROLE_ACCESS_DETAILS, ROLE_ACCESS_PROTECTED_SERVICES})
56  	PackageFamily getPackageFamily(
57  			@WebParam(name = "basename") String basename) throws AuthenticationException;
58  
59  	/**
60  	 * Returns the package details on the given package file id.
61  	 *
62  	 * @param file The SHA1 hash of the package file.
63  	 * @return the package details on the given package file id.
64  	 * @throws AuthenticationException In case of this service requires authentication and the current user session
65  	 *                                 is not authenticated or doesn't have the right to access the service.
66  	 */
67  	@WebMethod
68  	@WebResult(name = "packageDetails")
69  	@RequiredRoles({ROLE_RUN_PACKAGE_QUERIES, ROLE_ACCESS_DETAILS, ROLE_ACCESS_PROTECTED_SERVICES})
70  	PackageDetails getPackageDetailsById(
71  			@WebParam(name = "packageFileId") FileIdentifier file) throws AuthenticationException;
72  
73  	/**
74  	 * Returns the package details on the given package file ids.
75  	 *
76  	 * @param files The SHA1 hashes of the package files.
77  	 * @return the package details on the given package file ids.
78  	 * @throws AuthenticationException In case of this service requires authentication and the current user session
79  	 *                                 is not authenticated or doesn't have the right to access the service.
80  	 */
81  	@WebMethod
82  	@WebResult(name = "packageDetails")
83  	@ResponseWrapper( // Adding a custom response wrapper to support 'null' values inside the returned collection.
84  			className = "com.trendmicro.grid.acl.l0.wrappers.GetPackageDetailsListByIdResponse")
85  	@RequiredRoles({ROLE_RUN_PACKAGE_QUERIES, ROLE_ACCESS_DETAILS, ROLE_ACCESS_PROTECTED_SERVICES})
86  	Collection<PackageDetails> getPackageDetailsListById(
87  			@WebParam(name = "packageFileId") BatchCollection<FileIdentifier> files) throws AuthenticationException;
88  
89  	/**
90  	 * Returns the package details on the given package name.
91  	 *
92  	 * @param packageName The name the package.
93  	 * @return the package details on the given package name.
94  	 * @throws AuthenticationException In case of this service requires authentication and the current user session
95  	 *                                 is not authenticated or doesn't have the right to access the service.
96  	 */
97  	@WebMethod
98  	@WebResult(name = "packageDetails")
99  	@RequiredRoles({ROLE_RUN_PACKAGE_QUERIES, ROLE_ACCESS_DETAILS, ROLE_ACCESS_PROTECTED_SERVICES})
100 	PackageDetails getPackageDetailsByName(
101 			@WebParam(name = "packageName") String packageName) throws AuthenticationException;
102 
103 	/**
104 	 * Returns the package details on the given package names.
105 	 *
106 	 * @param packageNames The names the packages to lookup.
107 	 * @return the package details on the given package names.
108 	 * @throws AuthenticationException In case of this service requires authentication and the current user session
109 	 *                                 is not authenticated or doesn't have the right to access the service.
110 	 */
111 	@WebMethod
112 	@WebResult(name = "packageDetails")
113 	@ResponseWrapper( // Adding a custom response wrapper to support 'null' values inside the returned collection.
114 			className = "com.trendmicro.grid.acl.l0.wrappers.GetPackageDetailsListByNameResponse")
115 	@RequiredRoles({ROLE_RUN_PACKAGE_QUERIES, ROLE_ACCESS_DETAILS, ROLE_ACCESS_PROTECTED_SERVICES})
116 	Collection<PackageDetails> getPackageDetailsListByName(
117 			@WebParam(name = "packageName") BatchCollection<String> packageNames) throws AuthenticationException;
118 }