Class WmiQueryHandler

java.lang.Object
oshi.util.platform.windows.WmiQueryHandler
All Implemented Interfaces:
WmiQueryExecutor
@ThreadSafe public class WmiQueryHandler extends Object implements WmiQueryExecutor
Utility to handle WMI Queries. Designed to be extended with user-customized behavior.

  • Constructor Details

    • WmiQueryHandler

      protected WmiQueryHandler()
      Creates the WMI query handler. Subclasses may override via setInstanceClass(Class).

  • Method Details

    • createInstance

      public static WmiQueryHandler createInstance()
      Factory method to create an instance of this class. To override this class, use setInstanceClass(Class) to define a subclass which extends WmiQueryHandler.
      Returns:
      An instance of this class or a class defined by setInstanceClass(Class)

    • setInstanceClass

      public static void setInstanceClass(Class<? extends WmiQueryHandler> instanceClass)
      Define a subclass to be instantiated by createInstance(). The class must extend WmiQueryHandler.
      Parameters:
      instanceClass - The class to instantiate with createInstance().

    • queryWMI

      public <T extends Enum<T>> WbemcliUtil.WmiResult<T> queryWMI(WbemcliUtil.WmiQuery<T> query)
      Query WMI for values. Makes no assumptions on whether the user has previously initialized COM.
      Type Parameters:
      T - WMI queries use an Enum to identify the fields to query, and use the enum values as keys to retrieve the results.
      Parameters:
      query - A WmiQuery object encapsulating the namespace, class, and properties
      Returns:
      a WmiResult object containing the query results, wrapping an EnumMap

    • queryWMI

      public <T extends Enum<T>> WbemcliUtil.WmiResult<T> queryWMI(WbemcliUtil.WmiQuery<T> query, boolean initCom)
      Query WMI for values.
      Type Parameters:
      T - WMI queries use an Enum to identify the fields to query, and use the enum values as keys to retrieve the results.
      Parameters:
      query - A WmiQuery object encapsulating the namespace, class, and properties
      initCom - Whether to initialize COM. If true, initializes COM before the query and uninitializes after. If false, assumes the user has initialized COM separately. This can improve WMI query performance.
      Returns:
      a WmiResult object containing the query results, wrapping an EnumMap

    • queryWMI

      public <T extends Enum<T>> WmiResult<T> queryWMI(WmiQuery<T> query)
      Description copied from interface: WmiQueryExecutor
      Query WMI for values. Initializes and uninitializes COM for each query.
      Specified by:
      queryWMI in interface WmiQueryExecutor
      Type Parameters:
      T - the enum type for the query properties
      Parameters:
      query - the WMI query
      Returns:
      the query results

    • queryWMI

      public <T extends Enum<T>> WmiResult<T> queryWMI(WmiQuery<T> query, boolean initCom)
      Description copied from interface: WmiQueryExecutor
      Query WMI for values.
      Specified by:
      queryWMI in interface WmiQueryExecutor
      Type Parameters:
      T - the enum type for the query properties
      Parameters:
      query - the WMI query
      initCom - whether to initialize COM for this query. If false, assumes COM is already initialized.
      Returns:
      the query results

    • handleComException

      protected void handleComException(WbemcliUtil.WmiQuery<?> query, COMException ex)
      COM Exception handler. Logs at debug level for known-optional classes, otherwise warns.
      Parameters:
      query - a WbemcliUtil.WmiQuery object.
      ex - a COMException object.

    • initCOM

      public boolean initCOM()
      Initializes COM library and sets security to impersonate the local user
      Returns:
      True if COM was initialized and needs to be uninitialized, false otherwise
      Throws:
      COMException - if COM initialization fails with an unexpected error

    • initCOM

      protected boolean initCOM(int coInitThreading)
      Initializes COM with a specific threading model
      Parameters:
      coInitThreading - The threading model
      Returns:
      True if COM was initialized and needs to be uninitialized, false otherwise
      Throws:
      COMException - if COM initialization fails with an unexpected error

    • unInitCOM

      public void unInitCOM()
      UnInitializes COM library. This should be called once for every successful call to initCOM.

    • getComThreading

      public int getComThreading()
      Returns the current threading model for COM initialization, as OSHI is required to match if an external program has COM initialized already.
      Returns:
      The current threading model

    • switchComThreading

      public int switchComThreading()
      Switches the current threading model for COM initialization, as OSHI is required to match if an external program has COM initialized already.
      Returns:
      The new threading model after switching

    • switchComThreadingFrom

      public int switchComThreadingFrom(int expected)
      Switches the current threading model only if it still matches the expected value, avoiding a toggle race when multiple threads call initCOM() concurrently.
      Parameters:
      expected - the threading model observed before the failed initCOM attempt
      Returns:
      the new threading model if switched, or the current value if already switched by another thread

    • isSecurityInitialized

      public boolean isSecurityInitialized()
      Security only needs to be initialized once. This boolean identifies whether that has happened.
      Returns:
      Returns the securityInitialized.

    • getWmiTimeout

      public int getWmiTimeout()
      Gets the current WMI timeout. WMI queries will fail if they take longer than this number of milliseconds. A value of -1 is infinite (no timeout).
      Returns:
      Returns the current value of wmiTimeout.

    • setWmiTimeout

      public void setWmiTimeout(int wmiTimeout)
      Sets the WMI timeout. WMI queries will fail if they take longer than this number of milliseconds.
      Parameters:
      wmiTimeout - The wmiTimeout to set, in milliseconds. To disable timeouts, set timeout as -1 (infinite).