Scylla Documentation Logo Documentation
  • Server
    • Scylla Open Source
    • Scylla Enterprise
    • Scylla Alternator
  • Cloud
    • Scylla Cloud
    • Scylla Cloud Docs
  • Tools
    • Scylla Manager
    • Scylla Monitoring Stack
    • Scylla Operator
  • Drivers
    • CQL Drivers
    • DynamoDB Drivers
Download
Menu
Scylla Java Driver Manual OSGi

OSGi¶

The driver is available as an OSGi bundle. More specifically, the following maven artifacts are valid OSGi bundles:

  • java-driver-core

  • java-driver-query-builder

  • java-driver-mapper-runtime

  • java-driver-core-shaded

Note: some of the driver dependencies are not valid OSGi bundles. Most of them are optional, and the driver can work properly without them (see the Integration>Driver dependencies section for more details); in such cases, the corresponding packages are declared with optional resolution in Import-Package directives. However, if you need to access such packages in an OSGi container you MUST wrap the corresponding jar in a valid OSGi bundle and make it available for provisioning to the OSGi runtime.

Using the shaded jar¶

java-driver-core-shaded shares the same bundle name as java-driver-core (com.datastax.oss.driver.core). It can be used as a drop-in replacement in cases where you have an explicit version of dependency in your project different than that of the driver’s. Refer to shaded jar for more information.

Using a custom ClassLoader¶

In several places of the driver configuration it is possible to specify the class name of something to be instantiated by the driver such as the reconnection policy. This is accomplished using reflection, which uses a ClassLoader. By default, the driver uses its own bundle’s ClassLoader to instantiate classes by reflection. This is typically adequate as long as the driver bundle has access to the bundle where the implementing class resides.

However if the default ClassLoader cannot load the implementing class, you may encounter an error like this:

java.lang.ClassNotFoundException: com.datastax.oss.MyCustomReconnectionPolicy

Similarly, it also happens that the default ClassLoader is able to load the implementing class but is not able to ascertain whether that class implements the expected parent type. In these cases you may encounter an error such as:

java.lang.IllegalArgumentException: Expected class ExponentialReconnectionPolicy
(specified by advanced.reconnection-policy.class) to be a subtype of
com.datastax.oss.driver.api.core.connection.ReconnectionPolicy

This is occurring because there is a disparity in the ClassLoaders used between the driver code and the ClassLoader used to reflectively load the class (in this case, ExponentialReconnectionPolicy).

To overcome these issues, you may specify a ClassLoader instance when constructing a Session by using withClassLoader().

Alternatively, if you have access to the BundleContext (for example, if you are creating the session in an Activator class) you can also obtain the bundle’s ClassLoader the following way:

BundleContext bundleContext = ...;
Bundle bundle = bundleContext.getBundle();
BundleWiring bundleWiring = bundle.adapt(BundleWiring.class);
ClassLoader classLoader = bundleWiring.getClassLoader();
CqlSession session = CqlSession.builder()
    .withClassLoader(classLoader)
    .build();

Using a custom ClassLoader for application-bundled configuration resources¶

In addition to specifying a ClassLoader when constructing a Session, you can also specify a ClassLoader instance on certain DriverConfigLoader methods for cases when your OSGi application bundle provides overrides to driver configuration defaults. This is typically done by including an application.conf file in your application bundle.

For example, you can use DriverConfigLoader.fromDefaults(ClassLoader) to use the driver’s default configuration mechanism while specifying a different class loader:

BundleContext bundleContext = ...;
Bundle bundle = bundleContext.getBundle();
BundleWiring bundleWiring = bundle.adapt(BundleWiring.class);
ClassLoader classLoader = bundleWiring.getClassLoader();

CqlSession session = CqlSession.builder()
    .withClassLoader(classLoader)
    .withConfigLoader(DriverConfigLoader.fromDefaults(classLoader))
    .build();

The above configuration will look for resources named application.conf inside the application bundle, using the right class loader for that.

Similarly, if you want to use programmatic configuration in you application bundle, but still want to be able to provide some configuration in an application.conf file, you can use DriverConfigLoader.programmaticBuilder(ClassLoader):

BundleContext bundleContext = ...;
Bundle bundle = bundleContext.getBundle();
BundleWiring bundleWiring = bundle.adapt(BundleWiring.class);
ClassLoader classLoader = bundleWiring.getClassLoader();
DriverConfigLoader loader =
    DriverConfigLoader.programmaticBuilder(classLoader)
        .withDuration(DefaultDriverOption.REQUEST_TIMEOUT, Duration.ofSeconds(5))
        .startProfile("slow")
        .withDuration(DefaultDriverOption.REQUEST_TIMEOUT, Duration.ofSeconds(30))
        .endProfile()
        .build();
CqlSession session = CqlSession.builder()
    .withClassLoader(classLoader)
    .withConfigLoader(loader)
    .build();

The above configuration will honor all programmatic settings, but will look for resources named application.conf inside the application bundle, using the right class loader for that.

What does the “Error loading libc” DEBUG message mean?¶

The driver is able to perform native system calls through JNR in some cases, for example to achieve microsecond resolution when generating timestamps.

Unfortunately, some of the JNR artifacts available from Maven are not valid OSGi bundles and cannot be used in OSGi applications.

JAVA-1127 has been created to track this issue, and there is currently no simple workaround short of embedding the dependency, which we’ve chosen not to do.

Because native calls are not available, it is also normal to see the following log lines when starting the driver:

[main] DEBUG - Error loading libc
java.lang.NoClassDefFoundError: jnr/ffi/LibraryLoader
...
[main] INFO - Could not access native clock (see debug logs for details), falling back to Java
system clock
PREVIOUS
Mapper interface
NEXT
Query builder
  • 4.13.0.x
    • 4.13.0.x
    • 4.12.0.x
    • 4.11.1.x
    • 4.10.0.x
    • 4.7.2.x
    • 3.11.2.x
    • 3.11.0.x
    • 3.10.2.x
    • 3.7.2.x
  • Java Driver for Scylla and Apache Cassandra®
  • API Documentation
  • Manual
    • API conventions
    • Case sensitivity
    • Core driver
      • Address resolution
      • Asynchronous programming
      • Authentication
      • Bill of Materials (BOM)
      • Compression
      • Configuration
        • Reference configuration
      • Control connection
      • Custom codecs
      • Detachable types
      • Using the driver in GraalVM native images
      • Query idempotence
      • Integration
      • Load balancing
      • Logging
      • Metadata
        • Node metadata
        • Schema metadata
        • Token metadata
      • Metrics
      • Native protocol
      • Non-blocking programming
      • Paging
      • Performance
      • Connection pooling
      • Query timestamps
      • Reactive Style Programming
      • Reconnection
      • Request tracker
      • Retries
      • Using the shaded JAR
      • Speculative query execution
      • SSL
      • Statements
        • Batch statements
        • Per-query keyspace
        • Prepared statements
        • Simple statements
      • Temporal types
      • Request throttling
      • Query tracing
      • Tuples
      • User-defined types
    • Developer docs
      • Administrative tasks
      • Common infrastructure
        • Concurrency
        • Driver context
        • Event bus
      • Native protocol layer
      • Netty pipeline
      • Request execution
    • Mapper
      • Integration
        • Kotlin
        • Lombok
        • Java 14 Records
        • Scala
      • DAOs
        • Custom result types
        • Delete methods
        • GetEntity methods
        • Increment methods
        • Insert methods
        • Null saving strategy
        • Query methods
        • Query provider methods
        • Select methods
        • SetEntity methods
        • Statement attributes
        • Update methods
      • Entities
      • Mapper interface
    • OSGi
    • Query builder
      • Conditions
      • DELETE
      • Idempotence in the query builder
      • INSERT
      • Relations
      • Schema builder
        • Aggregate
        • Function
        • Index
        • Keyspace
        • Materialized View
        • Table
        • Type
      • SELECT
      • Terms
      • TRUNCATE
      • UPDATE
  • Upgrade guide
  • Frequently asked questions
  • Changelog
  • Create an issue
  • Edit this page

On this page

  • OSGi
    • Using the shaded jar
    • Using a custom ClassLoader
      • Using a custom ClassLoader for application-bundled configuration resources
    • What does the “Error loading libc” DEBUG message mean?
Logo
Docs Contact Us About Us
Mail List Icon Slack Icon
© 2022, ScyllaDB. All rights reserved.
Last updated on 25 May 2022.
Powered by Sphinx 4.3.2 & ScyllaDB Theme 1.2.2