Package com.chilkatsoft.chilkat2

Class Global

java.lang.Object
com.chilkatsoft.chilkat2.ChilkatObject
com.chilkatsoft.chilkat2.Global
All Implemented Interfaces:
AutoCloseable
public class Global extends ChilkatObject
<section class="global-summary">

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

Call UnlockBundle once during application startup to unlock Chilkat components for use throughout the process.

Global defaults

Configure process-wide defaults such as ANSI code page handling, DNS caching behavior, IPv6 preference, and NTLM version selection.

Diagnostics and logging

Enable additional diagnostic behavior such as verbose TLS logging and thread-pool logging when troubleshooting difficult runtime issues.

Async thread pool

Control the limits and behavior of Chilkat's internal thread pool used by asynchronous task-based methods.

Network-related behavior

Adjust DNS and IP-version preferences that can affect how Chilkat classes resolve names and establish network connections.

Compatibility options

Set specialized process-wide options for interoperability scenarios, such as special PKCS#7 encoding behavior.

Common pattern: Create a 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.

For an extended overview, see Global Class Overview.

</section>

Instances hold a native Chilkat object: close them with ChilkatObject.close() (try-with-resources) when done; an unclosed instance is freed when it becomes unreachable.

See Also:
Online reference

  • Constructor Details

    • Global

      public Global()
      Creates a new Global object.

  • Method Details

    • getAnsiCodePage

      public int getAnsiCodePage()
      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.

      Returns:
      the value of the AnsiCodePage property

    • setAnsiCodePage

      public void setAnsiCodePage​(int value)
      Sets the AnsiCodePage property; see getAnsiCodePage().
      Parameters:
      value - the new value

    • getAutoQBDecode

      public boolean getAutoQBDecode()
      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.
      Returns:
      the value of the AutoQBDecode property

    • setAutoQBDecode

      public void setAutoQBDecode​(boolean value)
      Sets the AutoQBDecode property; see getAutoQBDecode().
      Parameters:
      value - the new value

    • getDefaultNtlmVersion

      public int getDefaultNtlmVersion()
      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.
      Returns:
      the value of the DefaultNtlmVersion property

    • setDefaultNtlmVersion

      public void setDefaultNtlmVersion​(int value)
      Sets the DefaultNtlmVersion property; see getDefaultNtlmVersion().
      Parameters:
      value - the new value

    • getDefaultUtf8

      public boolean getDefaultUtf8()
      Sets the default value of the Utf8 property for each Chilkat class.

      In Chilkat v11.0.0 and later, the default value is true. Before v11.0.0, it was false.

      Returns:
      the value of the DefaultUtf8 property

    • setDefaultUtf8

      public void setDefaultUtf8​(boolean value)
      Sets the DefaultUtf8 property; see getDefaultUtf8().
      Parameters:
      value - the new value

    • getDnsTimeToLive

      public int getDnsTimeToLive()
      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.
      Returns:
      the value of the DnsTimeToLive property

    • setDnsTimeToLive

      public void setDnsTimeToLive​(int value)
      Sets the DnsTimeToLive property; see getDnsTimeToLive().
      Parameters:
      value - the new value

    • getEnableDnsCaching

      public boolean getEnableDnsCaching()
      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.
      Returns:
      the value of the EnableDnsCaching property

    • setEnableDnsCaching

      public void setEnableDnsCaching​(boolean value)
      Sets the EnableDnsCaching property; see getEnableDnsCaching().
      Parameters:
      value - the new value

    • getMaxThreads

      public int getMaxThreads()
      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.
      Returns:
      the value of the MaxThreads property

    • setMaxThreads

      public void setMaxThreads​(int value)
      Sets the MaxThreads property; see getMaxThreads().
      Parameters:
      value - the new value

    • getPreferIpv6

      public boolean getPreferIpv6()
      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.

      Returns:
      the value of the PreferIpv6 property

    • setPreferIpv6

      public void setPreferIpv6​(boolean value)
      Sets the PreferIpv6 property; see getPreferIpv6().
      Parameters:
      value - the new value

    • getThreadPoolLogPath

      public String getThreadPoolLogPath()
      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.
      Returns:
      the value of the ThreadPoolLogPath property

    • setThreadPoolLogPath

      public void setThreadPoolLogPath​(String value)
      Sets the ThreadPoolLogPath property; see getThreadPoolLogPath().
      Parameters:
      value - the new value (not null)

    • getUncommonOptions

      public String getUncommonOptions()
      This is a catch-all property to be used for uncommon needs. This property defaults to the empty string, and should typically remain empty.
      Returns:
      the value of the UncommonOptions property

    • setUncommonOptions

      public void setUncommonOptions​(String value)
      Sets the UncommonOptions property; see getUncommonOptions().
      Parameters:
      value - the new value (not null)

    • getUnlockStatus

      public int getUnlockStatus()
      Indicates the unlocked status for the last call to UnlockBundle. The possible values are:
      1. Not unlocked. (Still in locked state.)
      2. Unlocked with in fully-functional trial mode.
      3. 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.

      Returns:
      the value of the UnlockStatus property (read-only)

    • getUsePkcsConstructedEncoding

      public boolean getUsePkcsConstructedEncoding()
      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.)
      Returns:
      the value of the UsePkcsConstructedEncoding property

    • setUsePkcsConstructedEncoding

      public void setUsePkcsConstructedEncoding​(boolean value)
      Sets the UsePkcsConstructedEncoding property; see getUsePkcsConstructedEncoding().
      Parameters:
      value - the new value

    • getVerboseTls

      public boolean getVerboseTls()
      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.

      Returns:
      the value of the VerboseTls property

    • setVerboseTls

      public void setVerboseTls​(boolean value)
      Sets the VerboseTls property; see getVerboseTls().
      Parameters:
      value - the new value

    • dnsClearCache

      public void 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 - if the operation fails; ChilkatException.getLastErrorText() says why

    • finalizeThreadPool

      public void 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 - if the operation fails; ChilkatException.getLastErrorText() says why

    • threadPoolLogLine

      public void threadPoolLogLine​(String str)
      Logs a line to the thread pool log file.
      Parameters:
      str - the str argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why

    • unlockBundle

      public void unlockBundle​(String bundleUnlockCode)
      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 CLASS_NAME 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.

      Parameters:
      bundleUnlockCode - the bundleUnlockCode argument (not null)
      Throws:
      ChilkatException - if the operation fails; ChilkatException.getLastErrorText() says why