View Javadoc
1   /*
2    * Logback: the reliable, generic, fast and flexible logging framework.
3    * Copyright (C) 1999-2026, QOS.ch. All rights reserved.
4    *
5    * This program and the accompanying materials are dual-licensed under
6    * either the terms of the Eclipse Public License v2.0 as published by
7    * the Eclipse Foundation
8    *
9    *   or (per the licensee's choosing)
10   *
11   * under the terms of the GNU Lesser General Public License version 2.1
12   * as published by the Free Software Foundation.
13   */
14  
15  package ch.qos.logback.core.util;
16  
17  import ch.qos.logback.core.Context;
18  import ch.qos.logback.core.status.InfoStatus;
19  import ch.qos.logback.core.status.WarnStatus;
20  
21  import java.lang.module.ModuleDescriptor;
22  import java.util.Optional;
23  
24  import static ch.qos.logback.core.CoreConstants.CODES_URL;
25  import static ch.qos.logback.core.CoreConstants.NA;
26  
27  // depender depends on dependency
28  
29  // dependency synonym dependee (only use dependency)
30  // depender synonym dependent (only use depender)
31  
32  /**
33   * Utility class for handling and validating version information of various artifacts.
34   *
35   * <p>It is used by logback-classic, logback-access-common, logback-access-jetty11, logback-access-tomcat, etc.
36   * to alert users about version discrepancies between depender and dependency artifacts.
37   * </p>
38   *
39   * @since 1.5.25
40   */
41  public class VersionUtil {
42  
43      static final String DEPENDER_S_WAS_EXPECTING_PATTERN = "Depender [%s] was expecting version %s for dependency [%s] but found version %s";
44      /**
45       * @since 1.5.30
46       */
47      Context context;
48  
49      /**
50       * Instance methods allow for polymorphism, static methods do not.
51       *
52       *
53       * @param context
54       * @since 1.5.30
55       */
56      protected VersionUtil(Context context) {
57          this.context = context;
58      }
59  
60      static public String nonNull(String input) {
61          if (input == null) {
62              return NA;
63          } else {
64              return input;
65          }
66      }
67  
68      /**
69       * Retrieves the version of an artifact from the artifact's module metadata.
70       *
71       * <p>If the module or its descriptor does not provide a version, the method returns null.
72       * </p>
73       *
74       * @param aClass a class from which to retrieve the version information
75       * @return the version of class' module as a string, or null if the version cannot be determined
76       */
77      static private String getVersionOfClassByModule(Class<?> aClass) {
78          Module module = aClass.getModule();
79          if (module == null)
80              return null;
81  
82          ModuleDescriptor md = module.getDescriptor();
83          if (md == null)
84              return null;
85          Optional<String> opt = md.rawVersion();
86          return opt.orElse(null);
87      }
88  
89     protected String getExpectedVersionOfDependencyByProperties(Class<?> dependerClass, String propertiesFileName, String dependencyNameAsKey) {
90          // derived classes should override
91          return null;
92      }
93  
94  
95      /**
96       * Compares the versions of a depender and a dependency to determine if they are equal.
97       * Updates the context's status manager with version information and logs a warning
98       * if the versions differ.
99       *
100      * @since 1.5.26
101      */
102     static public void checkForVersionEquality(Context context, String dependerVersion, String dependencyVersion, String dependerName, String dependencyName) {
103         // the depender depends on the dependency
104         addFoundVersionStatus(context, dependerName, dependerVersion);
105 
106         dependerVersion = nonNull(dependerVersion);
107 
108         if (dependerVersion.equals(NA) || !dependerVersion.equals(dependencyVersion)) {
109             addFoundVersionStatus(context, dependencyName, dependencyVersion);
110             String discrepancyMsg = String.format("Versions of %s and %s are different or unknown.", dependencyName, dependerVersion);
111             context.getStatusManager().add(new WarnStatus(discrepancyMsg, context));
112         }
113     }
114 
115 
116     protected static void addFoundVersionStatus(Context context, String name, String version) {
117         String foundDependent = String.format("Found %s version %s", name, nonNull(version));
118         context.getStatusManager().add(new InfoStatus(foundDependent, context));
119     }
120 
121     protected static String nameToPropertiesFilename(String name) {
122         return name + "-dependencies.properties";
123     }
124 
125     /**
126      * Compares the expected version of a dependency with the actual version found and updates the status context.
127      * If the versions do not match, a warning is added to the context's status manager.
128      *
129      * <p>Note: This method is used be logback-access-jetty11/12 and logback-access-tomcat.</p>
130      *
131      */
132     public void compareExpectedAndFoundVersion(String actualDependencyVersion, Class<?> dependerClass, String dependerVersion,
133                                                       String dependerName, String dependencyName) {
134 
135         String propertiesFileName = nameToPropertiesFilename(dependerName);
136 
137         String expectedDependencyVersion = this.getExpectedVersionOfDependencyByProperties(dependerClass, propertiesFileName, dependencyName);
138         String safeExpectedDependencyVersion = nonNull(expectedDependencyVersion);
139 
140         addFoundVersionStatus(context, dependencyName, actualDependencyVersion);
141         addFoundVersionStatus(context, dependerName, dependerVersion);
142 
143         if (!safeExpectedDependencyVersion.equals(actualDependencyVersion)) {
144             String discrepancyMsg = String.format(DEPENDER_S_WAS_EXPECTING_PATTERN, dependerName,
145                     safeExpectedDependencyVersion, dependencyName, actualDependencyVersion);
146             context.getStatusManager().add(new WarnStatus(discrepancyMsg, context));
147 
148             String seeMsg = "See also "+CODES_URL+"#versionMismatch";
149             context.getStatusManager().add(new WarnStatus(seeMsg, context));
150 
151         }
152     }
153 }