com.helger.commons.lang.ServiceLoaderHelper Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of ph-commons Show documentation
Show all versions of ph-commons Show documentation
Java 1.8+ Library with tons of utility classes required in all projects
/*
* Copyright (C) 2014-2022 Philip Helger (www.helger.com)
* philip[at]helger[dot]com
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package com.helger.commons.lang;
import java.util.Iterator;
import java.util.ServiceLoader;
import javax.annotation.Nonnull;
import javax.annotation.Nullable;
import javax.annotation.concurrent.Immutable;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import com.helger.commons.ValueEnforcer;
import com.helger.commons.annotation.IsSPIImplementation;
import com.helger.commons.annotation.IsSPIInterface;
import com.helger.commons.annotation.ReturnsMutableCopy;
import com.helger.commons.cache.AnnotationUsageCache;
import com.helger.commons.collection.impl.CommonsArrayList;
import com.helger.commons.collection.impl.ICommonsList;
/**
* {@link ServiceLoader} helper class.
*
* @author boris
* @author Philip Helger
*/
@Immutable
public final class ServiceLoaderHelper
{
public static final AnnotationUsageCache CACHE_INTERFACE = new AnnotationUsageCache (IsSPIInterface.class);
public static final AnnotationUsageCache CACHE_IMPLEMENTATION = new AnnotationUsageCache (IsSPIImplementation.class);
private static final Logger LOGGER = LoggerFactory.getLogger (ServiceLoaderHelper.class);
private ServiceLoaderHelper ()
{}
/**
* Uses the {@link ServiceLoader} to load all SPI implementations of the
* passed class
*
* @param
* The implementation type to be loaded
* @param aSPIClass
* The SPI interface class. May not be null.
* @return A list of all currently available plugins
*/
@Nonnull
@ReturnsMutableCopy
public static ICommonsList getAllSPIImplementations (@Nonnull final Class aSPIClass)
{
return getAllSPIImplementations (aSPIClass, ClassLoaderHelper.getDefaultClassLoader (), null);
}
/**
* Uses the {@link ServiceLoader} to load all SPI implementations of the
* passed class
*
* @param
* The implementation type to be loaded
* @param aSPIClass
* The SPI interface class. May not be null.
* @param aClassLoader
* The class loader to use for the SPI loader. May not be
* null.
* @return A list of all currently available plugins
*/
@Nonnull
@ReturnsMutableCopy
public static ICommonsList getAllSPIImplementations (@Nonnull final Class aSPIClass, @Nonnull final ClassLoader aClassLoader)
{
return getAllSPIImplementations (aSPIClass, aClassLoader, null);
}
/**
* Uses the {@link ServiceLoader} to load all SPI implementations of the
* passed class
*
* @param
* The implementation type to be loaded
* @param aSPIClass
* The SPI interface class. May not be null.
* @param aLogger
* An optional logger to use. May be null.
* @return A list of all currently available plugins
*/
@Nonnull
@ReturnsMutableCopy
public static ICommonsList getAllSPIImplementations (@Nonnull final Class aSPIClass, @Nullable final Logger aLogger)
{
return getAllSPIImplementations (aSPIClass, ClassLoaderHelper.getDefaultClassLoader (), aLogger);
}
/**
* Uses the {@link ServiceLoader} to load all SPI implementations of the
* passed class
*
* @param
* The implementation type to be loaded
* @param aSPIClass
* The SPI interface class. May not be null.
* @param aClassLoader
* The class loader to use for the SPI loader. May not be
* null.
* @param aLogger
* An optional logger to use. May be null.
* @return A collection of all currently available plugins. Never
* null.
*/
@Nonnull
@ReturnsMutableCopy
public static ICommonsList getAllSPIImplementations (@Nonnull final Class aSPIClass,
@Nonnull final ClassLoader aClassLoader,
@Nullable final Logger aLogger)
{
ValueEnforcer.notNull (aSPIClass, "SPIClass");
ValueEnforcer.notNull (aClassLoader, "ClassLoader");
final Logger aRealLogger = aLogger != null ? aLogger : LOGGER;
if (aRealLogger.isTraceEnabled ())
aRealLogger.trace ("Trying to retrieve all SPI implementations of " + aSPIClass);
if (!CACHE_INTERFACE.hasAnnotation (aSPIClass))
if (LOGGER.isWarnEnabled ())
LOGGER.warn (aSPIClass + " should have the @IsSPIInterface annotation");
final ServiceLoader aServiceLoader = ServiceLoader. load (aSPIClass, aClassLoader);
final ICommonsList ret = new CommonsArrayList <> ();
// We use the iterator to be able to catch exceptions thrown
// when loading SPI implementations (e.g. the SPI implementation class does
// not exist)
final Iterator aIterator = aServiceLoader.iterator ();
while (aIterator.hasNext ())
{
try
{
final T aInstance = aIterator.next ();
if (!CACHE_IMPLEMENTATION.hasAnnotation (aInstance))
if (LOGGER.isWarnEnabled ())
LOGGER.warn (aInstance + " should have the @IsSPIImplementation annotation");
ret.add (aInstance);
}
catch (final Exception ex)
{
aRealLogger.error ("Unable to load an SPI implementation of " + aSPIClass, ex);
}
}
if (aRealLogger.isDebugEnabled ())
aRealLogger.debug ("Finished retrieving all " + ret.size () + " SPI implementations of " + aSPIClass);
return ret;
}
/**
* Uses the {@link ServiceLoader} to load all SPI implementations of the
* passed class and return only the first instance.
*
* @param
* The implementation type to be loaded
* @param aSPIClass
* The SPI interface class. May not be null.
* @return A collection of all currently available plugins. Never
* null.
*/
@Nullable
public static T getFirstSPIImplementation (@Nonnull final Class aSPIClass)
{
return getFirstSPIImplementation (aSPIClass, ClassLoaderHelper.getDefaultClassLoader (), null);
}
/**
* Uses the {@link ServiceLoader} to load all SPI implementations of the
* passed class and return only the first instance.
*
* @param
* The implementation type to be loaded
* @param aSPIClass
* The SPI interface class. May not be null.
* @param aClassLoader
* The class loader to use for the SPI loader. May not be
* null.
* @return A collection of all currently available plugins. Never
* null.
*/
@Nullable
public static T getFirstSPIImplementation (@Nonnull final Class aSPIClass, @Nonnull final ClassLoader aClassLoader)
{
return getFirstSPIImplementation (aSPIClass, aClassLoader, null);
}
/**
* Uses the {@link ServiceLoader} to load all SPI implementations of the
* passed class and return only the first instance.
*
* @param
* The implementation type to be loaded
* @param aSPIClass
* The SPI interface class. May not be null.
* @param aLogger
* An optional logger to use. May be null.
* @return A collection of all currently available plugins. Never
* null.
*/
@Nullable
public static T getFirstSPIImplementation (@Nonnull final Class aSPIClass, @Nullable final Logger aLogger)
{
return getFirstSPIImplementation (aSPIClass, ClassLoaderHelper.getDefaultClassLoader (), aLogger);
}
/**
* Uses the {@link ServiceLoader} to load all SPI implementations of the
* passed class and return only the first instance.
*
* @param
* The implementation type to be loaded
* @param aSPIClass
* The SPI interface class. May not be null.
* @param aClassLoader
* The class loader to use for the SPI loader. May not be
* null.
* @param aLogger
* An optional logger to use. May be null.
* @return A collection of all currently available plugins. Never
* null.
*/
@Nullable
public static T getFirstSPIImplementation (@Nonnull final Class aSPIClass,
@Nonnull final ClassLoader aClassLoader,
@Nullable final Logger aLogger)
{
final Logger aRealLogger = aLogger != null ? aLogger : LOGGER;
final ICommonsList aAll = getAllSPIImplementations (aSPIClass, aClassLoader, aRealLogger);
if (aAll.isEmpty ())
{
// No SPI implementation found
return null;
}
if (aAll.size () > 1)
{
// More than one implementation found
if (aRealLogger.isWarnEnabled ())
aRealLogger.warn ("Requested only one SPI implementation of " +
aSPIClass +
" but found " +
aAll.size () +
" - using the first one. Details: " +
aAll);
}
return aAll.getFirst ();
}
}