Deployment

The user-mode library comes in two pieces, both of which must be deployed along with the application:

  1. A JAR file, named cbfssync.jar
  2. A platform-native dynamic library with JNI (Java Native Interface), named as follows:
    • Windows: jnicbfssync26.dll (available for 32-bit (x86) and 64-bit (x64) processors)
    • Linux: libjnicbfssync.26.0.so (available for 32-bit (x86) and 64-bit (x64) processors)
    • macOS: libjnicbfssync26.0.dylib (available for x64 and ARM64 processors)

When deploying the application, copy both the JAR and the native library to the target system and place them next to the application.

Alternatively, the native library may be placed into one of directories, the paths to which are contained in the

  • Windows: PATH environment variable, such as C:\Windows\System32 (or C:\Windows\SysWOW64 when deploying a 32-bit application on a 64-bit Windows system)
  • Linux: LD_LIBRARY_PATH environment variable
  • macOS: DYLD_LIBRARY_PATH environment variable

NOTE: A deploy.jar file also may be used instead of cbfssync.jar; it is smaller, and does not contain Intellisense data or Javadoc content.

Java Runtime restrictions: Modern versions of Java Runtime give a warning or an error when the code of a Java library tries to use JNI or FFM. The possible solutions are:

  1. add the --enable-native-access=cbfssync.jar parameter to the command line when running your application. This will work if you specify the --modulepath parameter as well, and cbfssync.jar is in the directory referenced by the value of the "modulepath" parameter.
  2. add the --enable-native-access=ALL-UNNAMED parameter to the command line when running your application. Use this option when cbfssync.jar is on the classpath and you don't use the "modulepath" parameter or when cbfssync.jar is not in the directory referenced by the "modulepath" parameter..
  3. if you have an executable application that includes a manifest, add the Enable-Native-Access: ALL-UNNAMED statement to the manifest. Note that in this case, it is not possible to specify the particular library, and only "ALL-UNNAMED" value is permitted.

Windows:

The native library may alternatively be installed to the Windows system directory. This approach allows deploying both the 32-bit and 64-bit versions of the native library simultaneously, because each gets placed into the system directory that corresponds to the appropriate processor architecture.

Threading and Concurrency

The class utilizes different underlying technologies on different operating systems. Because of that, the threading model exposed to applications depends in part on the platform class runs on.

NOTE: Even when configured for minimal concurrency, the class always fires events in the context of some worker thread, and not in the thread the class was originally created on. Therefore, applications must be sure to synchronize operations between event handlers and other threads as necessary (including, but not limited to, calls to the class instance, unless a method is explicitly documented as callable within events).

Configuring Event Concurrency

The SerializeEvents property controls whether events relating to different files should be allowed to fire in parallel on several worker threads, or serialized on a single worker thread. By default, this property is set to seOnMultipleThreads, and events for different files are allowed to fire in parallel.

Windows: Generally speaking, the class always enforces per-file event serialization; that is, events relating to the same file are always fired in sequence regardless of the property value. With per-file event serialization already ensured, the most important concurrency-related consideration is whether to enforce multifile event serialization as well, which is what SerializeEvents controls. When SerializeEvents is set to seOnMultipleThreads, the MinWorkerThreadCount, MaxWorkerThreadCount, and WorkerInitialStackSize configuration settings let the application tune the worker thread pool. These settings are ignored when SerializeEvents is set to seOnOneWorkerThread.

Linux: When SerializeEvents is set to seOnMultipleThreads, the class may fire events related to the same file concurrently in several threads. If the application is not prepared for that, it should use seOnOneWorkerThread mode.

macOS: The events always fire on a single worker thread, and the SerializeEvents property has no effect.