1 package com.acumenvelocity.ath.controller;
2
3 import com.acumenvelocity.ath.common.Const;
4 import com.acumenvelocity.ath.common.ProjectProps;
5 import com.acumenvelocity.ath.common.Response;
6 import com.acumenvelocity.ath.model.VersionWrapper;
7
8 import io.swagger.oas.inflector.models.RequestContext;
9 import io.swagger.oas.inflector.models.ResponseContext;
10 import net.sf.okapi.common.Util;
11
12 /**
13 * REST Controller for handling ATH (AcumenTranslation Hub) version information.
14 * Provides endpoints for retrieving the current version of the ATH application.
15 *
16 * <p>
17 * This controller serves version information that can be used for:
18 * </p>
19 * <ul>
20 * <li>Client application compatibility checks</li>
21 * <li>System monitoring and health checks</li>
22 * <li>Debugging and support purposes</li>
23 * <li>API version negotiation</li>
24 * </ul>
25 *
26 * <p>
27 * <b>API Endpoint:</b> GET /version
28 * </p>
29 * <p>
30 * <b>Response Format:</b> JSON object containing version information
31 * </p>
32 *
33 * @author Acumen Velocity
34 * @version 1.0
35 * @since 1.0
36 */
37 public class VersionController {
38
39 /**
40 * Retrieves the current ATH application version.
41 *
42 * <p>
43 * This endpoint returns the version information stored in the project properties.
44 * The version is typically set during build time and read from application properties.
45 * </p>
46 *
47 * <p>
48 * <b>Response Scenarios:</b>
49 * </p>
50 * <ul>
51 * <li><b>200 Success:</b> Version information retrieved successfully</li>
52 * <li><b>404 Not Found:</b> Version information could not be detected or is missing</li>
53 * </ul>
54 *
55 * <p>
56 * <b>Example Success Response:</b>
57 * </p>
58 *
59 * <pre>
60 * {
61 * "version": "2.5.1"
62 * }
63 * </pre>
64 *
65 * <p>
66 * <b>Example Error Response:</b>
67 * </p>
68 *
69 * <pre>
70 * {
71 * "code": 404,
72 * "message": "Version cannot be detected"
73 * }
74 * </pre>
75 *
76 * @param request the HTTP request context provided by Swagger Inflector.
77 * Contains request metadata, headers, and parameters.
78 * This endpoint typically doesn't use request parameters.
79 * @return ResponseContext containing either:
80 * <ul>
81 * <li>HTTP 200 with version information in JSON format</li>
82 * <li>HTTP 404 with error message if version cannot be detected</li>
83 * </ul>
84 *
85 * @apiNote GET /version
86 * @see ProjectProps#getProjectPropValue(String)
87 * @see Const#ATH_PROP_CAT_VERSION
88 * @see VersionWrapper
89 */
90 public ResponseContext getVersion(RequestContext request) {
91 // Create response wrapper object for version information
92 VersionWrapper vw = new VersionWrapper();
93
94 // Retrieve version information from project properties
95 // The version is typically stored in application properties file under a specific key
96 String st = Const.CAT_VERSION;
97
98 // Validate that version information is present and not empty
99 // Uses Okapi's Util.isEmpty() for robust null/empty checking
100 if (Util.isEmpty(st)) {
101 // Return 404 error if version information is missing
102 // This indicates a configuration issue where version property is not set
103 return Response.error(404, "Version cannot be detected");
104 }
105
106 // Set the retrieved version string into the response wrapper
107 vw.setVersion(st);
108
109 // Return successful response with HTTP 200 status code
110 // The VersionWrapper object will be automatically serialized to JSON
111 return Response.success(200, vw);
112 }
113
114 }