Global Chilkat2 Java Reference Documentation
Global
Current Version: 11.7.0
Markdown version of this page for AI tools (v 11.7.0) · all AI docs
Chilkat.Global
Call
Configure process-wide defaults such as ANSI code page handling, DNS
caching behavior, IPv6 preference, and NTLM version selection.
Enable additional diagnostic behavior such as verbose TLS logging and
thread-pool logging when troubleshooting difficult runtime issues.
Control the limits and behavior of Chilkat's internal thread pool used by
asynchronous task-based methods.
Adjust DNS and IP-version preferences that can affect how Chilkat classes
resolve names and establish network connections.
Set specialized process-wide options for interoperability scenarios, such
as special PKCS#7 encoding behavior.
For an extended overview, see
Global Class Overview.
Unlock Chilkat and configure library-wide defaults, diagnostics, and async behavior.
Chilkat.Global is the Chilkat class for library-wide
initialization, licensing, default behavior, diagnostics, and thread-pool
control. Its most important method is UnlockBundle, which should
be called once at application startup before using other Chilkat classes. It
also provides settings for DNS caching, ANSI code page behavior, NTLM
version, IPv6 preference, verbose TLS logging, async task execution,
thread-pool limits, thread-pool logging, and special PKCS#7 encoding
behavior.
Library unlocking
UnlockBundle once during application startup to unlock
Chilkat components for use throughout the process.
Global defaults
Diagnostics and logging
Async thread pool
Network-related behavior
Compatibility options
Chilkat.Global object at application startup, call
UnlockBundle once, then set any process-wide defaults before
creating and using other Chilkat objects. Treat these settings as
application-wide configuration, not per-object state.
Object Creation
import com.chilkatsoft.chilkat2.ChilkatException;
import com.chilkatsoft.chilkat2.Global;
try (Global global = new Global()) {
// ... use global ...
} catch (ChilkatException e) {
System.out.println(e.getMessage()); // "Global.someMethod failed: <reason>"
System.out.println(e.getLastErrorText()); // the full log of the failed call
}Creates the underlying native Chilkat object. The native library (chilkat2java) is loaded the first time any Chilkat2 object is created; see the README in the download for where it is looked for (-Dchilkat2.library.path, a classpath resource, or java.library.path).
Releases the native object (Global is AutoCloseable, so try-with-resources calls it). Calling it again does nothing; any other method or property accessor called afterwards throws IllegalStateException. An object that is never closed is freed by a background cleaner once it becomes unreachable, but the garbage collector does not see native memory, so closing is the normal path. Objects returned by methods are owned by the caller too.
Returns true once close() has been called.
Errors
A method that fails throws ChilkatException, an unchecked exception carrying getClassName(), getMethodName(), getReason() (one line, also in the message) and getLastErrorText() (the full log, captured at the moment of the failure). The object remains usable. Methods that look something up and find nothing return null instead of throwing (each such method says so), and methods that answer a question (hasMember, isUnlocked, ...) return a plain boolean. Property accessors do not throw for Chilkat reasons.
A null string or object argument throws NullPointerException naming the parameter (except where a method documents that null is accepted), and a string containing U+0000 throws IllegalArgumentException.
Use an object from one thread at a time; it may be handed from one thread to another. The one cross-thread operation is setting setAbortCurrent(true) on an object that is busy in another thread (on the classes that have AbortCurrent). Unlocking: call new Global().unlockBundle("...") once at startup.
Properties
AnsiCodePage
int getAnsiCodePage()
void setAnsiCodePage(int value)
The default ANSI code page is determined at runtime based on the computer where the application happens to be running. For example, the ANSI code page for an application running on a Japanese computer is likely to be Shift_JIS (code page 932), whereas on a US-English computer it would be iso-8859-1 (or Windows-1252 which is essentially a superset of iso-8859-1).
If there is a desire for the Chilkat library to use a specific ANSI code page regardless of locale, then this property should be set to the desired code page. The default value of this property is the ANSI code page of the local computer.
topAutoQBDecode
boolean getAutoQBDecode()
void setAutoQBDecode(boolean value)
If set to true, then Q or B encoded strings can be passed in any string argument to any Chilkat method, and Chilkat will automatically decode the string before using it. This is meant to be a convenient way to use non-usascii literal strings in your source code. See the links below for an example and for a discussion about non-usascii literal strings.
DebugLogFilePath
String getDebugLogFilePath()
void setDebugLogFilePath(String value)
If set to a file path, this property logs the LastErrorText of each Chilkat method or property call to the specified file. This logging helps identify the context and history of Chilkat calls leading up to any crash or hang, aiding in debugging.
Enabling the VerboseLogging property provides more detailed information. This property is mainly used for debugging rare instances where a Chilkat method call causes a hang or crash, which should generally not happen.
Possible causes of hangs include:
- A timeout property set to 0, indicating an infinite timeout.
- A hang occurring within an event callback in the application code.
- An internal bug in the Chilkat code causing the hang.
DefaultNtlmVersion
int getDefaultNtlmVersion()
void setDefaultNtlmVersion(int value)
Selects the default NTLM protocol version to use for NTLM authentication for HTTP, POP3, IMAP, SMTP, and HTTP proxies. The default value is 2. This property may optionally be set to 1.
DnsTimeToLive
int getDnsTimeToLive()
void setDnsTimeToLive(int value)
If DNS caching is enabled, this is the time-to-live (in seconds) for a cached DNS lookup. A DNS lookup result older than this expiration time is discarded, and causes a new DNS lookup to occur. A value of 0 indicates an infinite time-to-live. The default value of this property is 0.
topEnableDnsCaching
boolean getEnableDnsCaching()
void setEnableDnsCaching(boolean value)
Controls whether DNS domain lookups (to resolve to IP addresses) are cached in memory. The default value is false, meaning that DNS caching is disabled.
LastErrorHtml
String getLastErrorHtml()
Provides HTML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastErrorText
String getLastErrorText()
Provides plain text information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
LastErrorXml
String getLastErrorXml()
Provides XML-formatted information about the last called method or property. If a method call fails or behaves unexpectedly, check this property for details. Note that information is available regardless of the method call's success.
topLastMethodSuccess
boolean getLastMethodSuccess()
void setLastMethodSuccess(boolean value)
Indicates the success or failure of the most recent method call: true means success, false means failure. This property remains unchanged by property setters or getters. This method is present to address challenges in checking for null or Nothing returns in certain programming languages. Note: This property does not apply to methods that return integer values or to boolean-returning methods where the boolean does not indicate success or failure.
MaxThreads
int getMaxThreads()
void setMaxThreads(int value)
The maximum number of thread pool threads. The default value is 100. The maximum value is 500. Note: Asynchronous worker threads are created on as needed up to the maximum.
topPreferIpv6
boolean getPreferIpv6()
void setPreferIpv6(boolean value)
If true, then use IPv6 over IPv4 when both are supported for a particular domain. The default value of this property is false, which will choose IPv4 over IPv6.
Note: Setting this property has the effect of also setting the default value of the PreferIpv6 property for other classes.
topThreadPoolLogPath
String getThreadPoolLogPath()
void setThreadPoolLogPath(String value)
If set, indicates the path of a log file to be used by the thread pool thread and each of the pool worker threads for logging async activity. Chilkat always appends to the log file. If the log file already exists, then new information will be appended.
topUncommonOptions
String getUncommonOptions()
void setUncommonOptions(String value)
This is a catch-all property to be used for uncommon needs. This property defaults to the empty string, and should typically remain empty.
topUnlockStatus
int getUnlockStatus()
Indicates the unlocked status for the last call to UnlockBundle. The possible values are:
- Not unlocked. (Still in locked state.)
- Unlocked with in fully-functional trial mode.
- Unlocked using a valid purchased unlock code.
Note: If UnlockBundle is called with a purchased unlock code, the UnlockStatus is correctly set to the value 2. This value is intentionally sticky. If a subsequent and redundant call to UnlockBundle happens, it is effectively a No-Op because the library is already unlocked. The UnlockStatus will not change.
If however, if the 1st call resulted in UnlockStatus = 1, and THEN the unlock method is called again with a purchased unlock code, the UnlockStatus should change from 1 to 2.
topUsePkcsConstructedEncoding
boolean getUsePkcsConstructedEncoding()
void setUsePkcsConstructedEncoding(boolean value)
This property should typically be left at the default value of false. If set to true, then Chilkat will use a constructed ASN.1 encoding for PCKS7 data. (This is an internal implementation option that normally does not matter, and should not matter. Some PKCS7 receiving systems might be picky, and this option can be used to satisfy this requirement.)
VerboseLogging
boolean getVerboseLogging()
void setVerboseLogging(boolean value)
If set to true, then the contents of LastErrorText (or LastErrorXml, or LastErrorHtml) may contain more verbose information. The default value is false. Verbose logging should only be used for debugging. The potentially large quantity of logged information may adversely affect peformance.
VerboseTls
boolean getVerboseTls()
void setVerboseTls(boolean value)
If set to true, then causes extremely verbose logging (in LastErrorText) all TLS connections in any Chilkat class. This property should only be used for troubleshooting TLS problems. The default value is false.
Note: This property only has effect on Chilkat objects not yet created. Set the property first, then instantiate the Chilkat object.
topVersion
String getVersion()
Methods
DnsClearCache
This function clears the Chilkat in-memory DNS cache, which stores hostname-to-IP address mappings to avoid repeated DNS lookups.
Note:
- The DNS cache is shared across all Chilkat objects, so clearing it will impact all such objects.
- Chilkat's DNS caching respects the TTL (time to live) of DNS records. If the TTL has expired since the initial lookup, Chilkat will perform a new DNS query and update the cache with the latest IP address.
Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.
FinalizeThreadPool
Called to stop and finalize all threads in the thread pool, and causes the thread pool thread to exit.
The following behaviors exist in v9.5.0.64 and later:
- All remaining asynchronous tasks are automatically canceled.
- Restores the thread pool to it's pristine state where no background threads are running.
It is a good idea to call this method at the very end of a program, just before it exits. This is especially true for programs written in VBScript, VB6, FoxPro, and PowerBuilder.
Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.
ThreadPoolLogLine
Logs a line to the thread pool log file.
Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.
UnlockBundle
Unlocks the entire Chilkat API for all classes. This should be called once at the beginning of a program. Once unlocked, objects of any Chilkat class may be instantiated and used. To unlock in fully-functional 30-day trial mode, pass any string, such as Hello, in bundleUnlockCode. If a license is purchased, then replace the Hello with the purchased unlock code.
After calling UnlockBundle once, the instance of the Global object may be discarded/deleted (assuming the programming language requires explicit deletes). Multiple calls to UnlockBundle are harmless. If the Chilkat API is already unlocked, the duplicate calls to UnlockBundle are no-ops.
Important: Unlocking sets a flag in memory to indicate the unlocked status. There are no licensing files, and there is no communication with any Chilkat servers. This means your application, script, etc. must call UnlockBundle once at the start each time it runs. The good thing is that your application can run on any computer -- there are no licensing files to worry about. Also: If an application forgets to call UnlockBundle, Chilkat will automatically unlock in trial mode, and this will eventually fail when the trial runs out. If you purchased a license, it is very important to make sure you call UnlockBundle with the purchased unlock code.
Throws ChilkatException on failure; e.getLastErrorText() (or the object's getLastErrorText()) explains why, and the object remains usable.