Skip to content

Commit bdad48c

Browse files
fmarco76claude
fmarco76
and
claude
committed
Add v1 REST API deprecation control with build-time flag
Introduce a new --v1-api-status flag to build.sh that provides granular control over the v1 REST API lifecycle, enabling smooth migration from v1 to v2 APIs. Four status levels are supported: 1. enabled (default): v1 API fully functional, backward compatible 2. deprecated: v1 functional but logs migration warnings at startup 3. disabled: v1 compiled but returns HTTP 410 Gone at runtime 4. dropped: v1 code completely excluded from compilation Build-time Integration: - build.sh accepts --v1-api-status={enabled|deprecated|disabled|dropped} - Passes value to CMake via -DV1_API_STATUS and to RPM via --define - Default value embedded in build.properties resource file - Maven filtering injects value into JAR at compile time Status: dropped (most significant changes): - Maven v1-api-dropped profile excludes v1 source files via pluginManagement - Maven v1-api-deps profile deactivated via -P'!v1-api-deps' - JAX-RS/RESTEasy BuildRequires and Requires skipped in pki.spec - JAX-RS/RESTEasy JARs not installed or transformed - CMake javadoc excludes v1 packages with --ignore-source-errors - RPM %post script removes old JAX-RS JARs from existing instances - Binary RPMs ~2-3MB smaller without v1 code and dependencies Status: disabled (clean error handling): - V1ApiDisabledResource catch-all JAX-RS resource created - Returns HTTP 410 Gone with JSON error instead of stack trace - All v1 Application classes register only V1ApiDisabledResource - Clean user experience: {"error": "v1 REST API has been disabled", ...} Status: deprecated (migration warning): - All v1 Application classes log prominent warning on startup - Full functionality maintained for transition period - Warnings visible in systemd journal and tomcat logs Runtime Behavior: - Build-time status becomes default runtime behavior - Administrators can override via -Dv1.api.status system property - All v1 Application classes (PKI, CA, KRA, OCSP, TKS, TPS) updated - Default behavior read from build.properties at runtime Implementation Details: - base/pom.xml: v1-api-deps and v1-api-dropped Maven profiles - base/server/pom.xml: Resource filtering for build.properties - base/server/src/main/resources/build.properties: New configuration file - base/server/src/main/java/.../V1ApiDisabledResource.java: New error handler - base/javadoc/CMakeLists.txt: Conditional package exclusion - pki.spec: Conditional dependencies and %post JAR cleanup - build.sh: Flag parsing and CMake/RPM integration Migration Path: 1. Deploy with --v1-api-status=deprecated (warnings, full function) 2. Monitor logs, notify users, allow migration period 3. Deploy with --v1-api-status=disabled (enforce v2, allow rollback) 4. Deploy with --v1-api-status=dropped (remove v1 code permanently) Testing: - Verified compilation with all four status values - Verified runtime behavior (enabled, deprecated, disabled) - Verified v1 code exclusion and JAR removal (dropped) - Verified HTTP 410 Gone responses (disabled) - Verified javadoc generation without v1 packages (dropped) Documentation: See docs/changes/v11.10.0/Packaging-Changes.adoc and Server-Changes.adoc Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
1 parent 6782ba9 commit bdad48c

17 files changed

Lines changed: 594 additions & 53 deletions

File tree

‎base/ca/src/main/java/org/dogtagpki/server/ca/rest/v1/CAApplication.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919
import org.dogtagpki.server.rest.v1.SelfTestService;
2020
import org.dogtagpki.server.rest.v1.SessionContextInterceptor;
2121
import org.dogtagpki.server.rest.v1.UserService;
22+
import org.dogtagpki.server.rest.v1.V1ApiStatusHelper;
2223

2324
@ApplicationPath("/v1")
2425
public class CAApplication extends Application {
@@ -30,6 +31,11 @@ public class CAApplication extends Application {
3031

3132
public CAApplication() {
3233

34+
// Check v1 API status
35+
if (V1ApiStatusHelper.checkV1ApiStatus("CA", classes, logger)) {
36+
return;
37+
}
38+
3339
// account
3440
classes.add(AccountService.class);
3541

‎base/common/pom.xml‎

Lines changed: 50 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -126,42 +126,6 @@
126126
</dependency>
127127
-->
128128

129-
<dependency>
130-
<groupId>pki-local</groupId>
131-
<artifactId>jboss-jaxrs-api_2.0_spec</artifactId>
132-
<version>1.0.0.Final</version>
133-
</dependency>
134-
135-
<dependency>
136-
<groupId>com.fasterxml.jackson.jaxrs</groupId>
137-
<artifactId>jackson-jaxrs-base</artifactId>
138-
<version>2.14.2</version>
139-
</dependency>
140-
141-
<dependency>
142-
<groupId>com.fasterxml.jackson.jaxrs</groupId>
143-
<artifactId>jackson-jaxrs-json-provider</artifactId>
144-
<version>2.14.2</version>
145-
</dependency>
146-
147-
<dependency>
148-
<groupId>org.jboss.logging</groupId>
149-
<artifactId>jboss-logging</artifactId>
150-
<version>3.4.1.Final</version>
151-
</dependency>
152-
153-
<dependency>
154-
<groupId>org.jboss.resteasy</groupId>
155-
<artifactId>resteasy-jaxrs</artifactId>
156-
<version>3.0.26.Final</version>
157-
</dependency>
158-
159-
<dependency>
160-
<groupId>org.jboss.resteasy</groupId>
161-
<artifactId>resteasy-jackson2-provider</artifactId>
162-
<version>3.0.26.Final</version>
163-
</dependency>
164-
165129
<dependency>
166130
<groupId>org.dogtagpki.jss</groupId>
167131
<artifactId>jss-base</artifactId>
@@ -176,6 +140,56 @@
176140

177141
</dependencies>
178142

143+
<profiles>
144+
<!-- Include v1 API dependencies unless status is "dropped" -->
145+
<profile>
146+
<id>v1-api-deps</id>
147+
<activation>
148+
<property>
149+
<name>v1.api.status</name>
150+
<value>!dropped</value>
151+
</property>
152+
</activation>
153+
<dependencies>
154+
<dependency>
155+
<groupId>pki-local</groupId>
156+
<artifactId>jboss-jaxrs-api_2.0_spec</artifactId>
157+
<version>1.0.0.Final</version>
158+
</dependency>
159+
160+
<dependency>
161+
<groupId>com.fasterxml.jackson.jaxrs</groupId>
162+
<artifactId>jackson-jaxrs-base</artifactId>
163+
<version>2.14.2</version>
164+
</dependency>
165+
166+
<dependency>
167+
<groupId>com.fasterxml.jackson.jaxrs</groupId>
168+
<artifactId>jackson-jaxrs-json-provider</artifactId>
169+
<version>2.14.2</version>
170+
</dependency>
171+
172+
<dependency>
173+
<groupId>org.jboss.logging</groupId>
174+
<artifactId>jboss-logging</artifactId>
175+
<version>3.4.1.Final</version>
176+
</dependency>
177+
178+
<dependency>
179+
<groupId>org.jboss.resteasy</groupId>
180+
<artifactId>resteasy-jaxrs</artifactId>
181+
<version>3.0.26.Final</version>
182+
</dependency>
183+
184+
<dependency>
185+
<groupId>org.jboss.resteasy</groupId>
186+
<artifactId>resteasy-jackson2-provider</artifactId>
187+
<version>3.0.26.Final</version>
188+
</dependency>
189+
</dependencies>
190+
</profile>
191+
</profiles>
192+
179193
<build>
180194
<plugins>
181195
<plugin>

‎base/javadoc/CMakeLists.txt‎

Lines changed: 39 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -56,6 +56,40 @@ if(((${Javadoc_VERSION_MAJOR} EQUAL 1) AND (${Javadoc_VERSION_MINOR} EQUAL 8)) O
5656
set(doclintstr "-Xdoclint:none")
5757
endif()
5858

59+
# Check v1 API status
60+
if(NOT DEFINED V1_API_STATUS)
61+
set(V1_API_STATUS "enabled")
62+
endif()
63+
# Always set as cache variable to make it available to all subdirectories
64+
set(V1_API_STATUS "${V1_API_STATUS}" CACHE STRING "v1 API status: enabled, deprecated, disabled, dropped" FORCE)
65+
message(STATUS "V1_API_STATUS = ${V1_API_STATUS}")
66+
67+
if("${V1_API_STATUS}" STREQUAL "dropped")
68+
# v1 dropped: exclude v1-specific packages from javadoc
69+
message(STATUS "v1 API dropped: excluding v1 packages from javadoc")
70+
# Don't include com.netscape.certsrv or org.dogtagpki (which are mostly v1 Resource interfaces)
71+
set(v1_subpackages "")
72+
# Exclude v1-specific packages (both client and server)
73+
set(exclude_packages
74+
"com.netscape.certsrv"
75+
"com.netscape.cms.servlet"
76+
"org.dogtagpki.server.rest.v1"
77+
"org.dogtagpki.server.tps"
78+
)
79+
# Don't include JAX-RS jars - they're not available when v1 is dropped
80+
# and javadoc will skip type checking for excluded packages
81+
set(jaxrs_classpath "")
82+
# Ignore source errors in excluded packages (transformed code references jakarta.ws.rs but jars have javax.ws.rs)
83+
set(v1_javadoc_opts "--ignore-source-errors")
84+
else()
85+
# v1 enabled/deprecated/disabled: include all packages
86+
message(STATUS "v1 API ${V1_API_STATUS}: including all packages in javadoc")
87+
set(v1_subpackages "com.netscape.certsrv" "org.dogtagpki")
88+
set(exclude_packages "")
89+
set(jaxrs_classpath ${JAXRS_API_JAR} ${RESTEASY_JAXRS_JAR})
90+
set(v1_javadoc_opts "")
91+
endif()
92+
5993
javadoc(pki-javadoc
6094
SOURCEPATH
6195
${CMAKE_SOURCE_DIR}/base/common/src/main/java
@@ -65,24 +99,24 @@ javadoc(pki-javadoc
6599
${CMAKE_CURRENT_BINARY_DIR}/javadoc/pki
66100
SUBPACKAGES
67101
com.netscape.cmsutil
68-
com.netscape.certsrv
69102
com.netscape.cmstools
70-
org.dogtagpki
103+
${v1_subpackages}
71104
${PKI_JAVADOC_SUBPACKAGES}
105+
EXCLUDE
106+
${exclude_packages}
72107
CLASSPATH
73108
${SLF4J_API_JAR} ${JAXB_API_JAR}
74109
${COMMONS_CLI_JAR} ${COMMONS_LANG3_JAR}
75110
${COMMONS_CODEC_JAR} ${COMMONS_IO_JAR}
76111
${LDAPJDK_JAR}
77112
${SERVLET_JAR} ${TOMCAT_CATALINA_JAR} ${TOMCAT_UTIL_JAR}
78113
${HTTPCLIENT_JAR} ${HTTPCORE_JAR}
79-
${JAXRS_API_JAR}
114+
${jaxrs_classpath}
80115
${JACKSON_CORE_JAR}
81116
${JACKSON_ANNOTATIONS_JAR}
82117
${JACKSON_DATABIND_JAR}
83118
${JACKSON_MODULE_JAXB_ANNOTATIONS_JAR}
84119
${JAKARTA_ANNOTATION_API_JAR}
85-
${RESTEASY_JAXRS_JAR}
86120
${JSS_JAR}
87121
${JSS_TOMCAT_JAR}
88122
${JSS_TOMCAT_9_0_JAR}
@@ -98,6 +132,7 @@ javadoc(pki-javadoc
98132
-version
99133
-quiet
100134
${doclintstr}
135+
${v1_javadoc_opts}
101136
)
102137

103138
add_dependencies(javadoc pki-javadoc)

‎base/kra/src/main/java/org/dogtagpki/server/kra/rest/v1/KRAApplication.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
import org.dogtagpki.server.rest.v1.SelfTestService;
1919
import org.dogtagpki.server.rest.v1.SessionContextInterceptor;
2020
import org.dogtagpki.server.rest.v1.UserService;
21+
import org.dogtagpki.server.rest.v1.V1ApiStatusHelper;
2122

2223
@ApplicationPath("/v1")
2324
public class KRAApplication extends Application {
@@ -29,6 +30,11 @@ public class KRAApplication extends Application {
2930

3031
public KRAApplication() {
3132

33+
// Check v1 API status
34+
if (V1ApiStatusHelper.checkV1ApiStatus("KRA", classes, logger)) {
35+
return;
36+
}
37+
3238
// account
3339
classes.add(AccountService.class);
3440

‎base/ocsp/src/main/java/org/dogtagpki/server/ocsp/rest/v1/OCSPApplication.java‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -18,6 +18,7 @@
1818
import org.dogtagpki.server.rest.v1.SelfTestService;
1919
import org.dogtagpki.server.rest.v1.SessionContextInterceptor;
2020
import org.dogtagpki.server.rest.v1.UserService;
21+
import org.dogtagpki.server.rest.v1.V1ApiStatusHelper;
2122

2223
@ApplicationPath("/v1")
2324
public class OCSPApplication extends Application {
@@ -29,6 +30,11 @@ public class OCSPApplication extends Application {
2930

3031
public OCSPApplication() {
3132

33+
// Check v1 API status
34+
if (V1ApiStatusHelper.checkV1ApiStatus("OCSP", classes, logger)) {
35+
return;
36+
}
37+
3238
// account
3339
classes.add(AccountService.class);
3440

‎base/pom.xml‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,11 @@
1414
<artifactId>pki-base-parent</artifactId>
1515
<packaging>pom</packaging>
1616

17+
<properties>
18+
<!-- v1 API status: enabled (default), deprecated, disabled, dropped -->
19+
<v1.api.status>enabled</v1.api.status>
20+
</properties>
21+
1722
<modules>
1823
<module>common</module>
1924
<module>tools</module>
@@ -32,4 +37,44 @@
3237
<module>console</module>
3338
</modules>
3439

40+
<profiles>
41+
<!-- Profile to drop v1 API completely (no compilation) -->
42+
<profile>
43+
<id>v1-api-dropped</id>
44+
<activation>
45+
<property>
46+
<name>v1.api.status</name>
47+
<value>dropped</value>
48+
</property>
49+
</activation>
50+
<build>
51+
<pluginManagement>
52+
<plugins>
53+
<plugin>
54+
<groupId>org.apache.maven.plugins</groupId>
55+
<artifactId>maven-compiler-plugin</artifactId>
56+
<configuration>
57+
<excludes combine.children="append">
58+
<!-- Exclude all v1 REST API files -->
59+
<exclude>**/rest/v1/**</exclude>
60+
<!-- Exclude v1 base classes -->
61+
<exclude>**/PKIService.java</exclude>
62+
<exclude>**/SubsystemService.java</exclude>
63+
<exclude>**/v1/PKIApplication.java</exclude>
64+
<!-- Exclude JAX-RS resource interfaces (v1 only) -->
65+
<exclude>**/*Resource.java</exclude>
66+
<!-- Exclude PATCH annotation -->
67+
<exclude>**/PATCH.java</exclude>
68+
<!-- Exclude TPS v1 services -->
69+
<exclude>**/TPSAccountService.java</exclude>
70+
<exclude>**/config/ConfigService.java</exclude>
71+
</excludes>
72+
</configuration>
73+
</plugin>
74+
</plugins>
75+
</pluginManagement>
76+
</build>
77+
</profile>
78+
</profiles>
79+
3580
</project>

‎base/server-webapp/src/main/java/org/dogtagpki/server/rest/v1/PKIApplication.java‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,11 +30,18 @@
3030
@ApplicationPath("/v1")
3131
public class PKIApplication extends Application {
3232

33+
public static org.slf4j.Logger logger = org.slf4j.LoggerFactory.getLogger(PKIApplication.class);
34+
3335
private Set<Object> singletons = new LinkedHashSet<>();
3436
private Set<Class<?>> classes = new LinkedHashSet<>();
3537

3638
public PKIApplication() {
3739

40+
// Check v1 API status
41+
if (V1ApiStatusHelper.checkV1ApiStatus("PKI", classes, logger)) {
42+
return;
43+
}
44+
3845
// services
3946
classes.add(AppService.class);
4047
classes.add(InfoService.class);

‎base/server/pom.xml‎

Lines changed: 33 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -28,15 +28,42 @@
2828
<version>${project.version}</version>
2929
</dependency>
3030

31-
<dependency>
32-
<groupId>org.jboss.resteasy</groupId>
33-
<artifactId>resteasy-servlet-initializer</artifactId>
34-
<version>3.0.26.Final</version>
35-
</dependency>
36-
3731
</dependencies>
3832

33+
<profiles>
34+
<!-- Include v1 API dependencies unless status is "dropped" -->
35+
<profile>
36+
<id>v1-api-deps</id>
37+
<activation>
38+
<activeByDefault>true</activeByDefault>
39+
</activation>
40+
<dependencies>
41+
<dependency>
42+
<groupId>org.jboss.resteasy</groupId>
43+
<artifactId>resteasy-servlet-initializer</artifactId>
44+
<version>3.0.26.Final</version>
45+
</dependency>
46+
</dependencies>
47+
</profile>
48+
</profiles>
49+
3950
<build>
51+
<resources>
52+
<resource>
53+
<directory>src/main/resources</directory>
54+
<filtering>true</filtering>
55+
<includes>
56+
<include>build.properties</include>
57+
</includes>
58+
</resource>
59+
<resource>
60+
<directory>src/main/resources</directory>
61+
<filtering>false</filtering>
62+
<excludes>
63+
<exclude>build.properties</exclude>
64+
</excludes>
65+
</resource>
66+
</resources>
4067
<plugins>
4168
<plugin>
4269
<groupId>org.apache.maven.plugins</groupId>

0 commit comments

Comments
 (0)