public interface Engine extends Closeable, Observable<EngineEvent>
To perform operations with the engine, a license key is required. The license key represents
a string that can be set via the "jxbrowser.license.key" system property or individually for
every Engine
using the EngineOptions.Builder.licenseKey(String)
method. If you
set the license key via the system property, then please make sure that you set it before
creating an Engine
instance.
The Chromium engine is running in a separate native process. Communication between the native and Java process is done through the Inter-Process Communication (IPC) layer that allows transferring data between two processes on a local machine.
The native process allocates memory and system resources that must be released. So, when the
engine is no longer needed, it must be closed through the Closeable.close()
method to shutdown the
native process and free all the allocated memory and system resources. For example:
Engine engine = Engine.newInstance(engineOptions); ... engine.close();
Any attempt to use an already closed engine will lead to the IllegalStateException
.
To get notifications that the Engine
instance has been closed subscribe to the
following event:
engine.on(EngineClosed.class, event -> { // The engine has been closed. });To get notifications that the
Engine
instance has been unexpectedly terminated use:
engine.on(EngineCrashed.class, event -> { // The engine has been unexpectedly terminated. });
Modifier and Type | Method and Description |
---|---|
java.util.List<Browser> |
browsers()
Returns an immutable list of alive
Browser instances including child popup browsers
for this engine or an empty list if this engine does not have any alive Browser . |
CookieStore |
cookieStore()
Returns the cookie store that allows managing cookies.
|
Downloads |
downloads()
Returns a service that allows managing downloads.
|
HttpAuthCache |
httpAuthCache()
Returns a service for working with HTTP authentication cache.
|
HttpCache |
httpCache()
Returns a service for working with HTTP cache.
|
MediaDevices |
mediaDevices()
Returns a service that allows managing media stream devices.
|
Network |
network()
Returns a service that allows working with network.
|
Browser |
newBrowser()
Creates a new
Browser instance and navigates it to the "about:blank" web page within
the Navigation.defaultTimeoutInSeconds() . |
static Engine |
newInstance(EngineOptions options)
Initializes and runs the Chromium engine with the given
options . |
EngineOptions |
options()
Returns the options the current engine was initialized with.
|
Permissions |
permissions()
Returns a service that allows managing permissions.
|
Plugins |
plugins()
Returns a service that allows configuring plugins.
|
Proxy |
proxy()
Returns a service that allows working with proxy.
|
SpellChecker |
spellChecker()
Returns a service that allows working with spell checking functionality.
|
ZoomLevels |
zoomLevels()
Returns a service that allows working with zoom.
|
on
static Engine newInstance(EngineOptions options)
options
.
Depending on the hardware performance, the initialization process might take several seconds. So, do not call this method in the application UI thread.
The method performs the following actions:
options
- the engine optionsEngine
EnvironmentException
- when the current environment is not supportedUserDataDirectoryCreationException
- when the given user data directory does not exist
and cannot be createdUserDataDirectoryAlreadyInUseException
- when the given user data directory is already
in use.IpcSetupFailureException
- when Inter-Process Communication (IPC) setup has been
failedChromiumProcessStartupFailureException
- when startup of the Chromium process has been
failedNoLicenseException
- when no license foundInvalidLicenseException
- when no valid license foundChromiumBinariesExtractionException
- when the verification of the Chromium binary
files has failed and the binaries cannot be extracted from the resourcesMissingDependencyException
- when Chromium fails to find the required system libraries.
This exception can only be thrown on LinuxEngineOptions options()
Browser newBrowser()
Browser
instance and navigates it to the "about:blank" web page within
the Navigation.defaultTimeoutInSeconds()
.Browser
instanceTimeoutException
- when the engine failed to create a browser instance within the
timeoutNavigationException
- when the navigation to the "about:blank" has failedjava.lang.IllegalStateException
- when the engine is already closedjava.util.List<Browser> browsers()
Browser
instances including child popup browsers
for this engine or an empty list if this engine does not have any alive Browser
.Browser
instances for this engineZoomLevels zoomLevels()
Proxy proxy()
Network network()
SpellChecker spellChecker()
CookieStore cookieStore()
HttpCache httpCache()
HttpAuthCache httpAuthCache()
MediaDevices mediaDevices()
Plugins plugins()
Downloads downloads()
Permissions permissions()