Package jenkins.util

Class SystemProperties

java.lang.Object
jenkins.util.SystemProperties
public class SystemProperties extends Object
Centralizes calls to System.getProperty(String) and related calls. This allows us to get values not just from environment variables but also from the ServletContext, so properties like jenkins.whatever.Clazz.disabled can be set in context.xml and the app server's boot script does not have to be changed.

This should be used to obtain hudson/jenkins "app"-level parameters (e.g. jenkins.whatever.Clazz.disabled), but not for system parameters (e.g. os.name).

If you run multiple instances of Jenkins in the same virtual machine and wish to obtain properties from context.xml, make sure these Jenkins instances use different ClassLoaders. Tomcat, for example, does this automatically. If you do not use different ClassLoaders, the values of properties specified in context.xml is undefined.

Property access is logged on Level.CONFIG. Note that some properties may be accessed by Jenkins before logging is configured properly, so early access to some properties may not be logged.

While it looks like it on first glance, this cannot be mapped to EnvVars, because EnvVars is only for build variables, not Jenkins itself variables.

Since:
2.236

  • Method Details

    • allowOnAgent

      public static void allowOnAgent(String key)
      Mark a key whose value should be made accessible in agent JVMs.
      Parameters:
      key - Property key to be explicitly allowed

    • getString

      @CheckForNull public static String getString(String key)
      Gets the system property indicated by the specified key. This behaves just like System.getProperty(java.lang.String), except that it also consults the ServletContext's "init" parameters.
      Parameters:
      key - the name of the system property.
      Returns:
      the string value of the system property, or null if there is no property with that key.
      Throws:
      NullPointerException - if key is null.
      IllegalArgumentException - if key is empty.

    • getString

      public static String getString(String key, @CheckForNull String def)
      Gets the system property indicated by the specified key, or a default value. This behaves just like System.getProperty(java.lang.String, java.lang.String), except that it also consults the ServletContext's "init" parameters.
      Parameters:
      key - the name of the system property.
      def - a default value.
      Returns:
      the string value of the system property, or null if the property is missing and the default value is null.
      Throws:
      NullPointerException - if key is null.
      IllegalArgumentException - if key is empty.

    • getString

      public static String getString(String key, @CheckForNull String def, Level logLevel)
      Gets the system property indicated by the specified key, or a default value. This behaves just like System.getProperty(java.lang.String, java.lang.String), except that it also consults the ServletContext's "init" parameters.
      Parameters:
      key - the name of the system property.
      def - a default value.
      logLevel - the level of the log if the provided key is not found.
      Returns:
      the string value of the system property, or null if the property is missing and the default value is null.
      Throws:
      NullPointerException - if key is null.
      IllegalArgumentException - if key is empty.

    • getBoolean

      public static boolean getBoolean(String name)
      Returns true if the system property named by the argument exists and is equal to the string "true". If the system property does not exist, return "false". if a property by this name exists in the ServletContext and is equal to the string "true". This behaves just like Boolean.getBoolean(java.lang.String), except that it also consults the ServletContext's "init" parameters.
      Parameters:
      name - the system property name.
      Returns:
      the boolean value of the system property.

    • getBoolean

      public static boolean getBoolean(String name, boolean def)
      Returns true if the system property named by the argument exists and is equal to the string "true", or a default value. If the system property does not exist, return "true" if a property by this name exists in the ServletContext and is equal to the string "true". If that property does not exist either, return the default value. This behaves just like Boolean.getBoolean(java.lang.String) with a default value, except that it also consults the ServletContext's "init" parameters.
      Parameters:
      name - the system property name.
      def - a default value.
      Returns:
      the boolean value of the system property.

    • optBoolean

      @CheckForNull public static Boolean optBoolean(String name)
      Returns Boolean.TRUE if the named system property exists and is equal to the string "true (ignoring case), returns Boolean.FALSE if the system property exists and doesn't equal "true otherwise returns null if the named system property does not exist.
      Parameters:
      name - the system property name.
      Returns:
      Boolean.TRUE, Boolean.FALSE or null
      Since:
      2.16

    • getDuration

      @CheckForNull public static Duration getDuration(@NonNull String name)
      Determines the duration value of the system property with the specified name.
      Parameters:
      name - property name.
      Returns:
      the property value as a duration.
      Since:
      2.516

    • getDuration

      @CheckForNull public static Duration getDuration(@NonNull String name, @CheckForNull ChronoUnit unit)
      Determines the duration value of the system property with the specified name.
      Parameters:
      name - property name.
      unit - the duration unit to use if the value doesn't specify one (defaults to `ms`)
      Returns:
      the property value as a duration.
      Since:
      2.516

    • getDuration

      @Nullable public static Duration getDuration(@NonNull String name, @CheckForNull Duration defaultValue)
      Determines the duration value of the system property with the specified name, or a default value.
      Parameters:
      name - property name.
      defaultValue - a default value
      Returns:
      the property value as a duration.
      Since:
      2.516

    • getDuration

      @Nullable public static Duration getDuration(@NonNull String name, @CheckForNull ChronoUnit unit, @CheckForNull Duration defaultValue)
      Determines the duration value of the system property with the specified name, or a default value.
      Parameters:
      name - property name.
      unit - the duration unit to use if the value doesn't specify one (defaults to `ms`)
      defaultValue - a default value
      Returns:
      the property value as a duration.
      Since:
      2.516

    • getInteger

      @CheckForNull public static Integer getInteger(String name)
      Determines the integer value of the system property with the specified name. This behaves just like Integer.getInteger(java.lang.String), except that it also consults the ServletContext's "init" parameters.
      Parameters:
      name - property name.
      Returns:
      the Integer value of the property.

    • getInteger

      public static Integer getInteger(String name, Integer def)
      Determines the integer value of the system property with the specified name, or a default value. This behaves just like Integer.getInteger(String,Integer), except that it also consults the ServletContext's "init" parameters. If neither exist, return the default value.
      Parameters:
      name - property name.
      def - a default value.
      Returns:
      the Integer value of the property. If the property is missing, return the default value. Result may be null only if the default value is null.

    • getInteger

      public static Integer getInteger(String name, Integer def, Level logLevel)
      Determines the integer value of the system property with the specified name, or a default value. This behaves just like Integer.getInteger(String,Integer), except that it also consults the ServletContext's "init" parameters. If neither exist, return the default value.
      Parameters:
      name - property name.
      def - a default value.
      logLevel - the level of the log if the provided system property name cannot be decoded into Integer.
      Returns:
      the Integer value of the property. If the property is missing, return the default value. Result may be null only if the default value is null.

    • getLong

      @CheckForNull public static Long getLong(String name)
      Determines the long value of the system property with the specified name. This behaves just like Long.getLong(java.lang.String), except that it also consults the ServletContext's "init" parameters.
      Parameters:
      name - property name.
      Returns:
      the Long value of the property.

    • getLong

      public static Long getLong(String name, Long def)
      Determines the integer value of the system property with the specified name, or a default value. This behaves just like Long.getLong(String,Long), except that it also consults the ServletContext's "init" parameters. If neither exist, return the default value.
      Parameters:
      name - property name.
      def - a default value.
      Returns:
      the Long value of the property. If the property is missing, return the default value. Result may be null only if the default value is null.

    • getLong

      public static Long getLong(String name, Long def, Level logLevel)
      Determines the integer value of the system property with the specified name, or a default value. This behaves just like Long.getLong(String, Long), except that it also consults the ServletContext's "init" parameters. If neither exist, return the default value.
      Parameters:
      name - property name.
      def - a default value.
      logLevel - the level of the log if the provided system property name cannot be decoded into Long.
      Returns:
      the Long value of the property. If the property is missing, return the default value. Result may be null only if the default value is null.