agi.foundation.infrastructure

(agi.foundation.core-2025r1.jar)

Class ServiceHelper

java.lang.Object

agi.foundation.infrastructure.ServiceHelper

public final class ServiceHelper
extends Object

Contains helpful methods for working with services and IServiceProvider.

Method Summary

Modifier and Type	Method and Description
static <T> T	getOptionalService(TypeLiteral<T> typeLiteralT, IServiceProvider serviceProvider) Gets a service from a given service provider, or null if the service does not exist.
static <T> T	getService(TypeLiteral<T> typeLiteralT, IServiceProvider serviceProvider) Gets a service from a given service provider, throwing a ServiceNotAvailableException if the service is not available.
static <T> T	getService(TypeLiteral<T> typeLiteralT, IServiceProvider serviceProvider, boolean throwIfNotAvailable) Gets a service from a given service provider.
static <T> T	getService(TypeLiteral<T> typeLiteralT, IServiceProvider serviceProvider, String exceptionMessage) Gets a service from a given service provider, throwing a ServiceNotAvailableException if the service is not available.
static boolean	hasService(IServiceProvider serviceProvider, Class<?> serviceType) Checks whether a service provider has a given service.
static Object	locateService(Class<?> serviceType, Object candidate) Convenience method for implementing IServiceProvider objects.
static <T extends IServiceProvider> Object	locateService(Class<?> serviceType, Object candidate, Iterable<T> additionalServiceProviders) Convenience method for implementing IServiceProvider objects.
static <T extends IServiceProvider> Object	locateService(Class<?> serviceType, Object candidate, T... additionalServiceProviders) Convenience method for implementing IServiceProvider objects.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getService

@Nonnull
public static <T> T getService(TypeLiteral<T> typeLiteralT,
                                         @Nonnull
                                         IServiceProvider serviceProvider)

Gets a service from a given service provider, throwing a ServiceNotAvailableException if the service is not available.

Type Parameters:

T - The type of service to obtain.

Parameters:

typeLiteralT - A TypeLiteral object representing the generic type T.

serviceProvider - The service provider from which to obtain the service.

Returns:

The requested service.

Throws:

ArgumentNullException - Thrown when the serviceProvider is null.

ServiceNotAvailableException - Thrown when the requested service is not available from the service provider.

getService

@Nonnull
public static <T> T getService(TypeLiteral<T> typeLiteralT,
                                         @Nonnull
                                         IServiceProvider serviceProvider,
                                         String exceptionMessage)

Gets a service from a given service provider, throwing a ServiceNotAvailableException if the service is not available.

Type Parameters:

T - The type of service to obtain.

Parameters:

typeLiteralT - A TypeLiteral object representing the generic type T.

serviceProvider - The service provider from which to obtain the service.

exceptionMessage - An error message to include in the exception if the service is unavailable.

Returns:

The requested service.

Throws:

ArgumentNullException - Thrown when the serviceProvider is null.

ServiceNotAvailableException - Thrown when the requested service is not available from the service provider.

getService

public static <T> T getService(TypeLiteral<T> typeLiteralT,
                               @Nonnull
                               IServiceProvider serviceProvider,
                               boolean throwIfNotAvailable)

Gets a service from a given service provider.

Type Parameters:

T - The type of service to obtain.

Parameters:

typeLiteralT - A TypeLiteral object representing the generic type T.

serviceProvider - The service provider from which to obtain the service.

throwIfNotAvailable - true if this method should throw a ServiceNotAvailableException if the requested service is not available from the service provider, or false if this method should simply return null if the service does not exist.

Returns:

The requested service.

Throws:

ArgumentNullException - Thrown when the serviceProvider is null.

ServiceNotAvailableException - Thrown when throwIfNotAvailable is true, and the requested service is not available from the service provider.

getOptionalService

@Nullable
public static <T> T getOptionalService(TypeLiteral<T> typeLiteralT,
                                                  @Nonnull
                                                  IServiceProvider serviceProvider)

Gets a service from a given service provider, or null if the service does not exist.

Type Parameters:

T - The type of service to obtain.

Parameters:

typeLiteralT - A TypeLiteral object representing the generic type T.

serviceProvider - The service provider from which to obtain the service.

Returns:

The requested service, or null if the service does not exist.

Throws:

ArgumentNullException - Thrown when the serviceProvider is null.

hasService

public static boolean hasService(@Nonnull
                                 IServiceProvider serviceProvider,
                                 @Nonnull
                                 Class<?> serviceType)

Checks whether a service provider has a given service.

Parameters:

serviceProvider - The service provider from which to obtain the service.

serviceType - The type of the service that is requested.

Returns:

true if the service provider returns a non-null service of the given type.

Throws:

ArgumentNullException - Thrown when serviceProvider or serviceType is null.

locateService

@Nullable
public static Object locateService(@Nonnull
                                              Class<?> serviceType,
                                              @Nonnull
                                              Object candidate)

Convenience method for implementing IServiceProvider objects. If candidate is an instance of serviceType, returns candidate, otherwise returns null.

Parameters:

candidate - A candidate object that could be of the requested serviceType.

serviceType - The type of the service that is requested.

Returns:

candidate if it is of type serviceType; otherwise null.

Throws:

ArgumentNullException - Thrown when serviceType or candidate is null.

locateService

@Nullable
public static <T extends IServiceProvider> Object locateService(@Nonnull
                                                                           Class<?> serviceType,
                                                                           @Nonnull
                                                                           Object candidate,
                                                                           @Nonnull
                                                                           T... additionalServiceProviders)

Convenience method for implementing IServiceProvider objects. If candidate is an instance of serviceType, returns candidate. Otherwise, checks additional IServiceProvider objects for any that return a non-null result for serviceType. Otherwise, returns null.

Type Parameters:

T - The type of additional service providers to search.

Parameters:

candidate - A candidate object that could be of the requested serviceType.

serviceType - The type of the service that is requested.

additionalServiceProviders - Additional service providers that will be checked, in order, for the requested service. The first non-null result will be returned.

Returns:

The requested service, or null if not found.

Throws:

ArgumentNullException - Thrown when serviceType, candidate, or additionalServiceProviders is null.

locateService

@Nullable
public static <T extends IServiceProvider> Object locateService(@Nonnull
                                                                           Class<?> serviceType,
                                                                           @Nonnull
                                                                           Object candidate,
                                                                           @Nonnull
                                                                           Iterable<T> additionalServiceProviders)

Convenience method for implementing IServiceProvider objects. If candidate is an instance of serviceType, returns candidate. Otherwise, checks additional IServiceProvider objects for any that return a non-null result for serviceType. Otherwise, returns null.

Type Parameters:

T - The type of additional service providers to search.

Parameters:

candidate - A candidate object that could be of the requested serviceType.

serviceType - The type of the service that is requested.

additionalServiceProviders - Additional service providers that will be checked, in order, for the requested service. The first non-null result will be returned.

Returns:

The requested service, or null if not found.

Throws:

ArgumentNullException - Thrown when serviceType, candidate, or additionalServiceProviders is null.