Package com.pnfsoftware.jeb.client

Class AbstractClientContext

java.lang.Object
com.pnfsoftware.jeb.util.events.EventSource
com.pnfsoftware.jeb.client.AbstractContext
com.pnfsoftware.jeb.client.AbstractClientContext
All Implemented Interfaces:
IClientContext, IEventSource
Direct Known Subclasses:
HeadlessClientContext
public abstract class AbstractClientContext extends AbstractContext implements IClientContext
Base context for official JEB clients. It is used by the RCP client context (GUI), the Controller (floating) context, as well as the headless runner.

On top of the abstract methods, which must be implemented, client code that override the following method must call the super-class method:
- initialize(String[])
- start()
- stop()

  • Field Details

    • defaultClientConfigPath

      public static final String defaultClientConfigPath
      Default client configuration filename.
      See Also:

    • defaultEnginesConfigPath

      public static final String defaultEnginesConfigPath
      Default engines configuration filename.
      See Also:

    • defaultTelemetryDatabasePath

      public static final String defaultTelemetryDatabasePath
      Default telemetry database filename.
      See Also:

    • defaultScriptsFolderName

      public static final String defaultScriptsFolderName
      Default scripts directory name.
      See Also:

    • defaultPluginsFolderName

      public static final String defaultPluginsFolderName
      Default plugins directory name.
      See Also:

    • coreOptions

      protected CoreOptions coreOptions
      A reference to core options that will be used when the JEB core context is instantiated in start(). Clients which decide to provide non-standard options should set this field before calling start().

    • args

      protected String[] args
      Command-line arguments remaining after client option parsing.

    • scriptpath

      protected String scriptpath
      Optional script path parsed from command-line arguments.

    • inputpath

      protected String inputpath
      Optional input path parsed from command-line arguments.

    • basicChecksPassed

      protected boolean basicChecksPassed
      True when startup checks completed successfully.

    • ugerrstr

      protected String ugerrstr
      Last user or license generation error string reported during startup.

    • CLIENT_RUNNING_FILENAME_PREFIX

      public static final String CLIENT_RUNNING_FILENAME_PREFIX
      Prefix used for lock files indicating that at least one JEB client is running.
      See Also:

    • INSTALLER_LOCK_FILENAME

      public static final String INSTALLER_LOCK_FILENAME
      Filename used by the installer to prevent client startup during updates.
      See Also:

  • Constructor Details

    • AbstractClientContext

      protected AbstractClientContext()
      Create a base client context.

  • Method Details

    • dumpProgramError

      protected boolean dumpProgramError(String str)
      Replace the program error log content.
      Parameters:
      str - content to write
      Returns:
      true if the error log was written successfully

    • checkRunningInstaller

      public boolean checkRunningInstaller()
      Determine whether the installer appears to be running.
      Returns:
      true if the installer lock is present and recent

    • initialize

      public void initialize(String[] argv)
      Initialize the client context from command-line arguments and configuration files.
      Parameters:
      argv - command-line arguments

    • start

      public void start() throws JebException
      Install update, if any. Allow the display of client-specific material such as: EULA, changelog, etc. If floating, initialize the floating client. Performs a license check for release builds. If not a controller, initialize a JEB core and engines.
      Throws:
      JebException - on initialization or licensing error

    • stop

      public void stop()
      Stop the client context and release telemetry and core resources.

    • assignCommandlineArguments

      protected void assignCommandlineArguments(String[] argv)
      Assigns args and inputpath. May overwrite configpath and engconfigpath. May assign scriptpath.
      Parameters:
      argv - command-line arguments

    • getArguments

      public String[] getArguments()
      Description copied from interface: IClientContext
      Get the input arguments provided to this client context. The returned array depends on how the context was instantiated and called.
      Specified by:
      getArguments in interface IClientContext
      Returns:
      an array (possibly empty) or null if arguments are irrelevant in the current context

    • getInputpath

      public String getInputpath()
      Get the current input path parsed from the command line, if any.
      Returns:
      the input path, or null if none was provided

    • getScriptpath

      public String getScriptpath()
      Get the script path parsed from the command line, if any.
      Returns:
      the script path, or null if none was provided

    • getNetworkUtility

      public Net getNetworkUtility()
      Get the shared network helper used by this client context.
      Returns:
      network helper

    • getPropertyDefinitionManager

      public IPropertyDefinitionManager getPropertyDefinitionManager()
      Get the property definition manager.
      Returns:
      property definition manager

    • getPropertyManager

      public IPropertyManager getPropertyManager()
      Get the property manager.
      Returns:
      property manager

    • getConfiguration

      public org.apache.commons.configuration2.Configuration getConfiguration()
      Get the raw client configuration object.
      Returns:
      configuration object

    • getTelemetry

      public com.pnfsoftware.jeb.client.telemetry.ITelemetryDatabase getTelemetry()
      Get the telemetry database handle.
      Returns:
      telemetry database handle

    • isDevelopmentMode

      public boolean isDevelopmentMode()
      Determine whether development mode is enabled.
      Returns:
      true if development mode is enabled

    • setDevelopmentMode

      public void setDevelopmentMode(boolean enabled)
      Enable or disable development mode.
      Parameters:
      enabled - true to enable development mode

    • getLogLevel

      public int getLogLevel()
      Get the configured global log level.
      Returns:
      log level

    • setLogLevel

      public void setLogLevel(int level)
      Set the configured global log level.
      Parameters:
      level - log level

    • getUuid

      public final long getUuid()
      Get the generated UUID associated with this client installation.
      Returns:
      UUID value, or 0 if unavailable

    • getPreferredLanguage

      public final String getPreferredLanguage()
      Get the preferred UI language code.
      Returns:
      preferred language code

    • setPreferredLanguage

      public final void setPreferredLanguage(String langcode)
      Set the preferred UI language code.
      Parameters:
      langcode - language code

    • shouldCheckUpdates

      public final boolean shouldCheckUpdates()
      Determine whether automatic update checks should be performed.
      Returns:
      true if update checks are enabled

    • getUpdateChannel

      public final int getUpdateChannel()
      Get the configured update channel.
      Returns:
      update channel

    • setUpdateChannel

      public final void setUpdateChannel(int channel)
      Set the accepted update channel.
      Parameters:
      channel - update channel

    • getLatestAvailableUpdate

      public final Version getLatestAvailableUpdate()
      Get the latest available update recorded in the client settings.
      Returns:
      latest available version, or null if none is recorded

    • setLatestAvailableUpdate

      public final void setLatestAvailableUpdate(Version version)
      Record the latest available update version in the client settings.
      Parameters:
      version - latest available version

    • shouldCheckPublicAnnouncements

      public final boolean shouldCheckPublicAnnouncements()
      Determine whether public announcement checks should be performed.
      Returns:
      true if announcement checks are enabled

    • getProxyString

      public final String getProxyString()
      Get the configured network proxy string.
      Returns:
      proxy settings string

    • setProxyString

      public final void setProxyString(String strProxyinfo)
      Set the network proxy string.
      Parameters:
      strProxyinfo - proxy settings string

    • getLastPublicAnnouncementId

      public final int getLastPublicAnnouncementId()
      Get the identifier of the last seen public announcement.
      Returns:
      last announcement id

    • setLastPublicAnnouncementId

      public final void setLastPublicAnnouncementId(int id)
      Set the identifier of the last seen public announcement.
      Parameters:
      id - last announcement id

    • isHeadless

      public boolean isHeadless()
      Determine whether this client context is headless.
      Returns:
      true if this context is headless

    • checkUpdate

      public abstract boolean checkUpdate()
      Not called locally: it is entirely up to the client to implement and decide who calls this method.
      Returns:
      true if an update was downloaded and should be applied

    • displayEula

      public abstract boolean displayEula(String eula)
      Display the end-user license agreement.

      Called from start().

      Parameters:
      eula - EULA text
      Returns:
      true if the user accepted the EULA

    • displayDemoInformation

      public abstract void displayDemoInformation(String demoInfo)
      Display information about demo restrictions.

      Called from start().

      Parameters:
      demoInfo - demo information text

    • onUpdatedSoftware

      public abstract void onUpdatedSoftware(String changelist, Version oldVersion)
      Notify a concrete client that a new version of JEB is being run for the first time.

      Called from start().

      Parameters:
      changelist - an optional change log
      oldVersion - the last version of JEB that was run (note: the current version is always available as a static public field)

    • retrieveLicenseKey

      public abstract String retrieveLicenseKey(String licdata)
      Retrieve a license key from the user.

      Called from start().

      Parameters:
      licdata - license data blob
      Returns:
      the license key entered by the user

    • notifySupportExpired

      public abstract void notifySupportExpired()
      Notify the client that support or subscription benefits expired.

      Called from start().

    • setupController

      public abstract boolean setupController()
      Ask the client to configure floating-controller settings if needed.

      Called from start().

      Returns:
      true if the controller was configured successfully

    • notifyFloatingClient

      public abstract void notifyFloatingClient(ControllerNotification notification)
      Notify the client of a floating-controller event.

      May be called from any thread.

      Parameters:
      notification - controller notification

    • generateLicenseInformation

      public static final String generateLicenseInformation()
      Format the current license information for display.
      Returns:
      formatted license information

    • ping

      public final int ping(int downloadOrder, int clientChannel, SoftwareBuildInfo sbi, IProgressCallback progressCallback, boolean verbose)
      Ping the JEB update server, and optionally download a JEB update on a compatible update channel.
      Parameters:
      downloadOrder - orders:
      • 0= no download (pure ping)
      • 1=soft download (download only if not a major version bump; else a code 3 may be returned if an update is available; the client must call this method once more with downloadOrder=2 to download the files)
      • 2= always download
      clientChannel - current client channel, ie maximum allowed channel a build must confirm to; see Version for a list of available channels
      sbi - optional information about the update
      progressCallback - optional callback, used if the update package is to be downloaded
      verbose - if true, messages are logged; if false, only important messages are logged
      Returns:
      return values are:
      • -2: error, corrupt update
      • -1: error, unknown
      • 0: up to date
      • 1: update available, but caller does not want to download
      • 2: update available and downloaded
      • 3: update available, not downloaded, (currently: the only reason is, it is a major update, eg v3 to v4) - use downloadOrder=2 to force the download and install

    • dumpUpdateToDisk

      public final void dumpUpdateToDisk(byte[] data, String password) throws IOException
      Persist a downloaded update archive and its optional password to disk.
      Parameters:
      data - update archive data
      password - optional archive password
      Throws:
      IOException - on write error

    • retrieveLatestPublicAnnouncement

      public final com.pnfsoftware.jeb.client.PublicAnnouncement retrieveLatestPublicAnnouncement()
      Retrieve the latest public announcement from the JEB server.
      Returns:
      the latest announcement object, or null on failure

    • getScriptsDirectory

      public final String getScriptsDirectory()
      Retrieve the JEB scripts directory path.
      Returns:
      never null, however, the path returned may not reference an existing directory

    • getScriptsDirfile

      public final File getScriptsDirfile()
      Retrieve and if necessary create the JEB scripts directory.
      Returns:
      the script directory

    • setScriptsDirectory

      public final void setScriptsDirectory(String folder)
      Set the JEB scripts directory path.
      Parameters:
      folder - scripts directory path

    • getUsedMemory

      public long getUsedMemory()
      Description copied from interface: IClientContext
      Get the amount of memory currently used by JEB.
      Specified by:
      getUsedMemory in interface IClientContext
      Returns:
      used memory in bytes

    • getMaxMemory

      public long getMaxMemory()
      Description copied from interface: IClientContext
      Get the theoretical maximum amount of memory that JEB can allocate and use.
      Specified by:
      getMaxMemory in interface IClientContext
      Returns:
      total theoretical memory that JEB could use, in bytes

    • getProcessId

      public long getProcessId()
      Description copied from interface: IClientContext
      Retrieve the process id of the Java VM executing JEB.
      Specified by:
      getProcessId in interface IClientContext
      Returns:
      JEB's PID

    • logMemoryUsage

      public final void logMemoryUsage()
      Log the current process memory usage.

    • formatMemoryUsage

      public static String formatMemoryUsage()
      Format the current process memory usage.
      Returns:
      formatted memory usage string

    • formatProcessInfo

      public static String formatProcessInfo(boolean inclPid, boolean inclMeminfo, boolean inclTimes, boolean inclCmdline)
      Format various process information bits. Each bit is formatted on a single line.
      Parameters:
      inclPid - true to include process identifier information
      inclMeminfo - true to include memory usage information
      inclTimes - true to include start time and CPU time information
      inclCmdline - true to include the full command line
      Returns:
      formatted process information

    • initializeEngines

      protected final void initializeEngines() throws JebException
      Initialize the core context and an engines context.
      Throws:
      JebException - on core or engines initialization error

    • getCoreContext

      public final ICoreContext getCoreContext()
      Get the JEB core instance. Should never be null unless an error happened in start() or the context is one of a floating controller.
      Returns:
      the core context, or null if unavailable

    • getEnginesContext

      public final IEnginesContext getEnginesContext()
      Get the JEB engines instance. Should never be null unless an error happened in start() or the context is one of a floating controller.
      Specified by:
      getEnginesContext in interface IClientContext
      Returns:
      the engines context, or null if unavailable

    • hasOpenedProject

      public final boolean hasOpenedProject()
      Determine whether a project is currently open.
      Returns:
      true if a project is open

    • getOpenedProject

      public final IRuntimeProject getOpenedProject()
      Retrieve the current project, if any. Same as getMainProject().
      Returns:
      may be null

    • closeOpenedProject

      public final boolean closeOpenedProject()
      Close the currently opened project, if any.
      Returns:
      true if a project was open and closed

    • getMainProject

      public IRuntimeProject getMainProject()
      Same as getOpenedProject().
      Specified by:
      getMainProject in interface IClientContext
      Returns:
      the main project, or null if none is open

    • closeMainProject

      public boolean closeMainProject()
      Same as closeOpenedProject().
      Specified by:
      closeMainProject in interface IClientContext
      Returns:
      true if a project was open and closed

    • open

      public IUnit open(String path) throws IOException
      Description copied from interface: IClientContext
      Convenience method used to create a JEB project (or retrieve the current project if one is opened), load a file artifact into the project, process it, and return the resulting top-level unit.

      If the input file is a JDB2 saved project, that project is opened and returned. The method will throw IllegalStateException if a project is already opened.

      Specified by:
      open in interface IClientContext
      Parameters:
      path - input file to be analyzed, or an existing project saved as a JDB2 database (*.jdb2)
      Returns:
      the top-level unit yielded from the analysis of the provided artifact; if the input path was a JDB2 project, the top-level unit of the first project's artifact is returned
      Throws:
      IOException - on IO error

    • getTransientStore

      public Map<Object,Object> getTransientStore()
      Description copied from interface: IClientContext
      Retrieve a reference to the transient store provided by this context. Clients may use this map to store context-level global objects. The store and its objects are not persisted with a project JDB2 database.

      Interface specifications for implementations:
      - Null keys are forbidden, null values are allowed
      - Insertion, retrieval and deletion are thread-safe
      - Iterating is not thread-safe
      - The insertion order is not guaranteed during iteration

      Specified by:
      getTransientStore in interface IClientContext
      Returns:
      a non-null read-write map

    • getControllerInterface

      public String getControllerInterface()
      Get the floating-controller interface or hostname.
      Returns:
      controller interface or hostname

    • setControllerInterface

      public void setControllerInterface(String iface)
      Set the floating-controller interface or hostname.
      Parameters:
      iface - controller interface or hostname

    • getControllerPort

      public int getControllerPort()
      Get the floating-controller port.
      Returns:
      controller port

    • setControllerPort

      public void setControllerPort(int port)
      Set the floating-controller port.
      Parameters:
      port - controller port

    • getControllerProtocol

      public int getControllerProtocol()
      Get the floating-controller protocol identifier.
      Returns:
      controller protocol identifier

    • setControllerProtocol

      public void setControllerProtocol(int protocol)
      Set the floating-controller protocol identifier.
      Parameters:
      protocol - controller protocol identifier

    • getControllerMessage

      public String getControllerMessage()
      Get the optional floating-controller message configured for this client.
      Returns:
      controller message