JExplorer Programmer’s Guide

Version: 3.5

  1. Introduction
  2. Requirements
  3. Architecture
  4. Browser Mode
  5. Hello World
  6. Loading URL
  7. Loading HTML
  8. Pop-ups
  9. JavaScript
  10. JavaScript Dialogs
  11. User-Agent
  12. DOM API
  13. Logging

1. Introduction

1.1. About This Document

This document represents a developer's guide to JExplorer library. Here you can find all required information regarding the use of JExplorer library in your Java application.

1.2. About JExplorer

JExplorer is a Java library that allows integrating with installed in operating system MS Internet Explorer web browser control into Java application. Integration with MS Internet Explorer is implemented via system native MSHTML library. With JExplorer you can embed MS IE web browser control to display modern web pages.

1.3. Examples and Demo

Almost all the examples in this guide can be found in the samples directory of JExplorer Distribution Package. The samples you can also find online.

JExplorer Web Start Online Demo you can find at http://www.teamdev.com/jexplorer#onlinedemo

1.4. Package

The structure of JExplorer Distribution Package (jexplorer-3.5.zip) is the following:

lib/
    jexplorer-3.5.jar    // JExplorer library
samples/                    // API samples
doc/javadoc/                // Public API JavaDocs
doc/guide/                  // Programmer's Guide
demo/
    jexplorerdemo.jar       // Demo application library
    jexplorerdemo.bat       // Executable *.bat to run Demo application on Windows
Readme.txt                  // Readme file
License agreement.txt       // License agreement

1.5. Installation

To use JExplorer library in your Java application you need to include all the JAR files from the lib directory of JExplorer Distribution Package. Your application class path should look like:

java -classpath jexplorer-3.5.jar <your-application-class>

The jexplorer-3.5.jar library contains native binaries. At the first run JExplorer extracts the binaries from the JAR file into user's temp folder. So, Java application must have rights to write to user's temp directory.

1.6. Licensing

JExplorer will be supported until June 30, 2019. Commercial licenses are currently not available for purchase, so this section is intended for the users who have acquired licenses prior to June 30, 2018.

If you have any licensing questions, please contact sales@teamdev.com.

JExplorer library requires a valid license (teamdev.licenses) file for operations.

Commercial License

License comes in two JARs: development.jar and runtime.jar. You need to include one of these JARs into your application class path to enable the license. The difference between Development and Runtime license is the following:

– you need to use the Development license (development.jar) for development purposes only. The number of licenses should be equal to the number of developers who use JExplorer in development. For example, if you have 10 developers involved into your project and only 4 of them work with JExplorer, you should purchase 4 licenses only.

– the Runtime license (runtime.jar) should be used when you distribute your software with JExplorer enclosed. For example, you can include the runtime.jar file into class path of your application production version. You can deploy the Runtime license with your application to unlimited number of end users.

License Information

In order to get information about the license, use the "teamdev.license.info" system property. The following code demonstrates how to enable license info printing in your application.

System.setProperty("teamdev.license.info", "true");
Browser browser = new Browser();

2. Requirements

JExplorer integrates with installed in operating system MS Internet Explorer.

  1. Microsoft Windows XP (SP2), 7, 8, 8.1, 10, Server 2003/2008/2012, 32-bit and 64-bit.
  2. MS Internet Explorer 6, 7, 8, 9, 10, 11. Both 32-bit and 64-bit.
  3. Oracle JDK/JRE 1.7.x and higher, 32-bit and 64-bit.

3. Architecture

JExplorer supports multi-process architecture and runs native code in separate JExplorer32.exe or JExplorer64.exe processes depending on JVM architecture.

By default each Browser instance is initialized with a new BrowserContext. For example:

Browser browser = new Browser();

BrowserContext is responsible for communication between Browser instance and its corresponding JExplorer.exe native process. Two Browser instances with different context, will use two different JExplorer.exe processes. For example:

Browser browserOne = new Browser(new BrowserContext()); // Starts JExplorer32.exe
Browser browserTwo = new Browser(new BrowserContext()); // Starts JExplorer32.exe

When you need to run two Browser instances in same native process (e.g. to share session cookies), you can use the following approach:

BrowserContext context = new BrowserContext();
Browser browserOne = new Browser(context); // Starts JExplorer32.exe
Browser browserTwo = new Browser(context); // Use already started JExplorer32.exe

JExplorer32.exe process is terminated automatically once you dispose the latest Browser instance that belongs to the process.

By default parent and child Browser instances are running in same JExplorer.exe process.

4. Browser Mode

MS Internet Explorer can display web pages using different versions of Internet Explorer via Browser Mode feature. In JExplorer by default web engine is configured to display web pages in MS IE 7 Browser Mode.

In case when MS Internet Explorer 11 is installed in your environment, you might want to enable MS IE 11 Browser Mode in JExplorer. To configure Browser Mode use the BrowserFeatures.enableBrowserMode(BrowserMode mode) method. For example:

// Enable MS IE 11 Browser Mode
BrowserFeatures.enableBrowserMode(BrowserMode.IE11);
Browser browser = new Browser();

Browser Mode is a global setting that is stored in Windows Registry. Once you set Browser Mode, all Browser instances will use it. To remove this setting and enabled default behavior (MS IE7 Browser Mode) use the BrowserFeatures.disableBrowserMode() method.

Browser Mode must be configure before you create any Browser instance.

5. Hello World

Once you configure Java project, include all JExplorer and license JAR files into your application class path, you should be able to run your first program with JExplorer:

import com.teamdev.jexplorer.Browser;
import javax.swing.*;
import java.awt.*;

public class HelloWorldSample {
    public static void main(String[] args) {
        Browser browser = new Browser();

        JFrame frame = new JFrame("JExplorer: Hello World");
        frame.setDefaultCloseOperation(WindowConstants.EXIT_ON_CLOSE);
        frame.add(browser, BorderLayout.CENTER);
        frame.setSize(400, 300);
        frame.setLocationRelativeTo(null);
        frame.setVisible(true);

        browser.setContent("<html><body><h1>Hello world!</h1></body></html>");
    }
}

This simple example above shows how to create a Browser component, embed it into Swing container, display it and load the "<html><body><h1>Hello world!</h1></body></html>" HTML string directly into the Browser.

When you run this sample you should see the following output:

Hello world example output

6. Loading URL

To load web page by its URL use the following method:

browser.navigate("http://www.google.com");

This method doesn't wait until web page is loaded completely. To find out when web page is loaded completely use the NavigationListener.mainDocumentCompleted(Browser browser, String url) event. For example:

browser.addNavigationListener(new NavigationAdapter() {
    @Override
    public void mainDocumentCompleted(Browser browser, String url) {
        // Web page is loaded completely
    }
});
browser.navigate("http://www.google.com");

To block current thread execution and wait until web page is loaded completely within a specified timeout, use the following approach:

try {
    Browser.invokeAndWaitLoadMainFrame(browser, new Callback<Browser>() {
        @Override
        public void call(Browser browser) {
            browser.navigate("http://www.google.com");
        }
    });
} catch (TimeoutException e) {
    // Web page wasn't loaded completely within a timeout
}
// Web page is loaded completely

By default timeout is set to 15 seconds. You can change default value via jexplorer.ipc.timeout.seconds system property or com.teamdev.jexplorer.internal.ipc.LatchUtil.WAIT_SECONDS.

7. Loading HTML

To load HTML content from string use the following method:

browser.setContent("<html><body><h1>Hello world!</h1></body></html>");

This method doesn't wait until HTML content is loaded and displayed completely. To find out when it's loaded see Loading URL.

8. Pop-ups

By default JExplorer supports and displays popup windows. To change default behavior you can register your own PopupHandler implementation. For example:

browser.setPopupHandler(new PopupHandler() {
    @Override
    public PopupContainer handlePopup() {
        return new PopupContainer() {
            @Override
            public void insertBrowser(final Browser browser) {
                final JFrame frame = new JFrame();
                frame.getContentPane().add(browser, BorderLayout.CENTER);
                frame.setSize(800, 600);
                frame.setLocationRelativeTo(null);
                frame.setVisible(true);

                frame.addWindowListener(new java.awt.event.WindowAdapter() {
                    @Override
                    public void windowClosing(WindowEvent e) {
                        browser.dispose();
                    }
                });

                browser.addDisposeListener(new DisposeListener() {
                    @Override
                    public void onDispose(Browser browser) {
                        SwingUtilities.invokeLater(new Runnable() {
                            @Override
                            public void run() {
                                frame.setVisible(false);
                                frame.dispose();
                            }
                        });
                    }
                });
            }
        };
    }
});

9. JavaScript

You can execute any JavaScript code on the loaded web page and get result of JavaScript code execution. The following code demonstrates how to execute JavaScript code and get return value:

JSValue returnValue = browser.executeScript("document.title");
if (returnValue.isString()) {
    System.out.println("Title = " + returnValue.getString());
}

The result of JavaScript execution is represented as JSValue. Using JSValue.isXXX() methods you can determine what value type it contains (e.g. String, Boolean, Number, Null). To extract value from JSValue use corresponding JSValue.getXXX() method.

Don't call browser.executeScript() in Java UI/EDT thread. JavaScript code you are trying to execute may cause Alert or other JavaScript UI dialog to be shown. In this case you might receive a deadlock.

10. JavaScript Dialogs

JExplorer supports and displays JavaScript dialogs such as Alert or Confirmation by default. Using DialogHandler you can handle JavaScript dialogs in your application. The following code demonstrates how to suppress all JavaScript dialogs:

browser.setDialogHandler(new DialogHandler() {
    @Override
    public int showDialog(String title, String text, int type) {
        // Suppress dialog and close it right away without displaying UI
        return DialogHandler.IDOK;
    }
});

In your DialogHandler implementation you can display your own customized dialogs.

11. User-Agent

JExplorer API allows modifying user-agent string sent to a web server when you load web page. The following code demonstrates how to do this:

Browser browser = new Browser();
browser.setUserAgent("MyUserAgent");
browser.navigate("http://whatsmyuseragent.com/");

To get default MS IE user-agent string use the Browser.getDefaultUserAgent() method.

12. DOM API

JExplorer provides DOM API that allows working with DOM of the loaded web page. You can access document, go through DOM structure, read HTML elements and their attributes, modify DOM structure, etc.

The following sample demonstrates how to access document of the loaded web page, find all A elements on the web page and print their text content:

import com.teamdev.jexplorer.Browser;
import com.teamdev.jexplorer.dom.DOMDocument;
import com.teamdev.jexplorer.dom.DOMNodeList;
import com.teamdev.jexplorer.event.NavigationAdapter;

import javax.swing.*;
import java.awt.*;

public class DOMGetElementsSample {
    public static void main(String[] args) {
        Browser browser = new Browser();

        JFrame frame = new JFrame();
        frame.setDefaultCloseOperation(WindowConstants.EXIT_ON_CLOSE);
        frame.add(browser, BorderLayout.CENTER);
        frame.setSize(800, 600);
        frame.setLocationRelativeTo(null);
        frame.setVisible(true);

        browser.addNavigationListener(new NavigationAdapter() {
            @Override
            public void mainDocumentCompleted(Browser browser, String url) {
                DOMDocument document = browser.getDocument();
                DOMNodeList elements = document.getElementsByTagName("a");
                int length = elements.getLength();
                for (int i = 0; i < length; i++) {
                    System.out.println("Text Content: " + elements.item(i).getTextContent());
                }
            }
        });
        browser.navigate("http://www.google.com");
    }
}

13. Logging

JExplorer logging system is based on Java Logging, so you can configure JExplorer logging using standard Java Logging API. For example, in order to access different JExplorer Loggers and specify the SEVERE log level you can use the following code:

import com.teamdev.jexplorer.LoggerProvider;
import java.util.logging.*;
...
LoggerProvider.getBrowserLogger().setLevel(Level.SEVERE);
LoggerProvider.getIPCLogger().setLevel(Level.SEVERE);
LoggerProvider.getProcessLogger().setLevel(Level.SEVERE);

The BrowserLogger is used to log browser messages.
The IPCLogger is used to log IPC (Inter-Process Communication) messages.
The ProcessLogger is used to log messages that are come from JExplorer.exe process.

By default the log level for all JExplorer loggers is set to Level.ALL.

Redirect logging to a file

To redirect all log messages of BrowserLogger to the "D:/jexplorer.log" file, you can use the following way:

Logger logger = LoggerProvider.getBrowserLogger();
FileHandler fileHandler = new FileHandler("D:/jexplorer.log");
logger.addHandler(fileHandler);
fileHandler.setFormatter(new SimpleFormatter());

You can redirect log messages of any JExplorer logger: BrowserLogger, IPCLogger or ProcessLogger.

Copyright © 2002-2021 TeamDev Ltd.