Each Browser instance must be initialized with BrowserContext. The BrowserContext instance holds the context needed for a browsing session and provides path to the directory where Chromium stores cookies, cache data files, etc.


The following code creates a new Browser instance initialized with default context: 

Browser browser = new Browser();

The code above equals to: 

Browser browser = new Browser(BrowserContext.defaultContext());

The BrowserContext.defaultContext() method returns default BrowserContext that is configured to store Chromium data files such as cookies, cache, etc. in user's temp directory on macOS and Linux and AppData\Local\JxBrowser on Windows. You can get path to the directory where data files are stored using the BrowserPreferences.getDefaultDataDir() method.


Two Browser instances with the same BrowserContext instances will use the same user data directory. As result they will share cookies and cache files. For example: 

BrowserContext context = new BrowserContext(
    new BrowserContextParams("C:\\my-data1"));
Browser browser1 = new Browser(context);
Browser browser2 = new Browser(context);

To create independent Browser instances that don't share cookies and cache data, you must initialize each Browser instance with a different BrowserContext instance configured to use a different data directory. For example: 

BrowserContext context1 = new BrowserContext(
    new BrowserContextParams("C:\\my-data1"));
Browser browser1 = new Browser(context1);

BrowserContext context2 = new BrowserContext(
    new BrowserContextParams("C:\\my-data2"));
Browser browser2 = new Browser(context2);

To get BrowserContext of the Browser instance you can use the browser.getContext() method.


Important to Know

Using several BrowserContext instances configured to use same data directory in a single or multiple Java application instances is forbidden. In this case Browser constructor will throw the BrowserException exception to prevent unexpected behavior or errors such as native crash in the Chromium engine.


If it's possible to launch more than one instance of your Java application at the same time on the same machine, then please don't create Browser instance in your application using default constructor. In this case both Browser instances running in different Java applications at the same time will be configured to use the same Chromium data directory which is forbidden. The BrowserException exception will be thrown when the second Java application instance will try to create a new Browser instance.


To solve this issue please make sure that only one instance of your Java application can be used at the same time. If you would like to let end users to run multiple instances of your Java application at the same time, then please make sure that each instance of your Java application configures JxBrowser library to use unique Chromium data directory.


Multiple instances of Java application:

App instance #1
Browser browser = new Browser(); // OK
 App instance #2
Browser browser = new Browser(); // <= BrowserException
No 
App instance #1
BrowserContext context = new BrowserContext(
    new BrowserContextParams("C:\\data"));
Browser browser = new Browser(context); // OK
 App instance #2
BrowserContext context = new BrowserContext(
    new BrowserContextParams("C:\\data"));
Browser browser = new Browser(context); // <= BrowserException
No 
App instance #1
BrowserContext context = new BrowserContext(
    new BrowserContextParams("C:\\data1"));
Browser browser = new Browser(context);
  App instance #2
BrowserContext context = new BrowserContext(
    new BrowserContextParams("C:\\data2"));
Browser browser = new Browser(context);
Yes 


A single Java application instance:

Browser browserOne = new Browser(); // OK

String dataDir = BrowserContext.defaultContext().getDataDir();
BrowserContext context = new BrowserContext(
    new BrowserContextParams(dataDir));
Browser browserTwo = new Browser(context); // <= BrowserException
No 
BrowserContext context1 = new BrowserContext(
    new BrowserContextParams("C:\\shared-data"));
Browser browser1 = new Browser(context1); // OK

BrowserContext context2 = new BrowserContext(
    new BrowserContextParams("C:\\shared-data"));
Browser browser2 = new Browser(context2); // <= BrowserException
No 
BrowserContext context1 = new BrowserContext(
    new BrowserContextParams("C:\\my-data1"));
Browser browser1 = new Browser(context1);
BrowserContext context2 = new BrowserContext(
    new BrowserContextParams("C:\\my-data2"));
Browser browser2 = new Browser(context2);
Yes 
Browser browser1 = new Browser();
Browser browser2 = new Browser();
Browser browser3 = new Browser(BrowserContext.defaultContext());
Yes 


Multiple BrowserContext Limitations

At the moment there is a limit on how many BrowserContext instances can be held by one Chromium process. Holding more than that limit can lead to unexpected crashes in Chromium process. The limit is around 50 instances of BrowserContext per process and varies depending on the operating system.


On Linux and MacOS Chromium does not release its file descriptors. That behavior leads to the file descriptors leak and after some point, it becomes impossible to create new BrowserContext instances because of hitting the hard limit of the file descriptors.


On Windows, new BrowserContext instances are acquiring thread-local storages from Chromium pool of thread-local storages and never releases them, which may lead to Chromium process crashes when trying to create new BrowserContext.


To avoid issues with multiple BrowserContext instances, the following approaches can be used:


1. Multiple Browser instances can use the same BrowserContext. If you do not need to create the Browser instances that don't share cookies, caches and other user data, you can use a single BrowserContext instance. For example:

BrowserContext browserContext = new BrowserContext(new BrowserContextParams(
        new File("user_data_dir").getAbsolutePath()));
Browser browserOne = new Browser(browserContext);
Browser browserTwo = new Browser(browserContext);


2. In case you need to use multiple Browser instances that don't share cookies and other user data and you have to create multiple BrowserContext instances, we recommend that you dispose all Browser instances periodically to destroy all created BrowserContext instances, and terminate Chromium native process to release file descriptors and other resources. After that, you can continue creating the new BrowserContext and Browser instances.