All Manuals > LispWorks User Guide and Reference Manual > 43 Android Java classes and methods

NextPrevUpTopContentsIndex

com.lispworks.Manager

Java class
Summary

public class com.lispworks.Manager

A Java class that defines methods for using Lisp on Android . It contains one essential method, com.lispworks.Manager.init, which loads and initializes LispWorks. It also contains methods to set error reporters that will get called when an error inside Lisp is not caught by user handlers or when report-error-to-java-host is called, some methods to define where messages from Lisp (calls to send-message-to-java-host or format-to-java-host) go, and some other utilities.

com.lispworks.Manager defines these methods and fields:

Initialization

public static int init(Context context , String deliverName, Runnable reporter)

public static int init(Context context)

public static int init(Context context, Runnable reporter)

public static int init(Context context, String deliverName)

 

public static int status()

public static int init_result_code()

public static String mInitErrorString = ""

 

public static boolean loadLibrary()

public static boolean loadLibrary(String deliverName)

final public static int STATUS_INITIALIZING = 0
final public static int STATUS_READY = 1
final public static int STATUS_NOT_INITIALIZED = -1
final public static int STATUS_ERROR = -2

final public static int INIT_ERROR_NO_LIBRARY = -2000
final public static int INIT_ERROR_NO_ASSET = -2001
final public static int INIT_ERROR_FAIL_HEAP = -2002

Error handling

public static void setErrorReporter(LispErrorReporter ler)

public static void setGuiErrorReporter(LispGuiErrorReporter ler)

public interface LispErrorReporter

public interface LispGuiErrorReporter

public static synchronized void clearBugFormLogs(int count)

public static void showBugFormLogs(Activity act)

public static String mInitErrorString = ""

public static int mMaxErrorLogsNumber = 5

Message handling

public interface MessageHandler

public void setMessageHandler(MessageHandler handler)

public static synchronized void setTextView(android.widget.TextView textview)

public static void addMessage(String message, int where)

public static int mMessagesMaxLength

final public static int ADDMESSAGE_RESET = 0
final public static int ADDMESSAGE_APPEND = 1
final public static int ADDMESSAGE_PREPEND = 2
final public static int ADDMESSAGE_APPEND_NO_SCROLL = 3
final public static int ADDMESSAGE_ADD = 4
final public static int ADDMESSAGE_ADD_NO_SCROLL = 5

Others

public static void setCurrentActivity(android.app.Activity)

public static ClassLoader getClassLoader()

public static Context getApplicationContext()

Notes

The com.lispworks.Manager class is part of the LispWorks distribution, inside the lispworks.jar file.

See also

Delivering for Android

com.lispworks.Manager.init

Method

public static int init(Context context)

public static int init(Context context, Runnable reporter)

public static int init(Context context, String deliverName)

public static int init(Context context, String deliverName, Runnable reporter)

Description

Load and initialize Lispworks asynchronously.

init first checks whether LispWorks is already initialized or in the process of initializing, and if it is returns immediately the appropriate value (STATUS_READY or STATUS_INITIALIZING). Otherwise it loads LispWorks, and initiates the initialization process on another thread. It returns before initialization finished.

The argument context is any object of class android.content.Context. init uses it to find the application context, and hence where the LispWorks heap is.

The argument reporter is a Runnable that is invoked (that is its run method is invoked) when LispWorks finished initialization. The invocation is on the main thread. The reporter in general should use com.lispworks.Manager.status to check that initializing LispWorks succeeded. Once the reporter is invoked and com.lispworks.Manager.status returned STATUS_READY, it is possible to make calls into Lisp by methods in com.lispworks.LispCalls. If reporter is not supplied, it is possible to know that LispWorks is ready by two other mechanisms:

The argument deliverName specifies the name of the delivered LispWorks, specifically the base name of the heap and the dynamic library. See deliver-to-android-project for discussion. The default for deliverName is "LispWorks", which is the default in deliver-to-android-project, so normally you do not need it.

init returns one of the STATUS_* constants. See the entry for com.lispworks.Manager.status.

init can be called repeatedly and it is thread-safe. The second and subsequent calls will not try to initialize it, unless the status is STATUS_ERROR, in which case it will try again. Each reporter that is passed to init is called independently. This is designed so if your application does not initialize LispWorks on startup, each part of it that relies on LispWorks can use com.lispworks.Manager.status to check whether LispWorks is ready, and if not call init with a reporter, and when the reporter is invoked check that com.lispworks.Manager.status returns STATUS_READY, and then rely on working LispWorks.

See also

com.lispworks.Manager.status
deliver-to-android-project
com.lispworks.Manager
Delivering for Android

com.lispworks.Manager.status

Method and Fields

public static int status()

final public static int STATUS_INITIALIZING = 0
final public static int STATUS_READY =1
final public static int STATUS_NOT_INITIALIZED = -1
final public static int STATUS_ERROR = -2

Description

Return the status of LispWorks:

STATUS_INITIALIZING

LispWorks started initializing but has not finished yet. Because com.lispworks.Manager.init is asynchronous, it typically returns this value.

STATUS_READY

LispWorks finished initializing.

STATUS_NOT_INITIALIZED

LispWorks has not started initializing, that is before com.lispworks.Manager.init was called.

STATUS_ERROR

There was an error during initialization that prevented initialization. The method com.lispworks.Manager.init_result_code and the field com.lispworks.Manager.mInitErrorString gives more information about the reason for failure.

See also

com.lispworks.Manager.init
com.lispworks.Manager.init_result_code
com.lispworks.Manager.mInitErrorString
Delivering for Android

com.lispworks.Manager.init_result_code

Method and Fields

public static int init_result_code()

final public static int INIT_ERROR_NO_LIBRARY = -2000
final public static int INIT_ERROR_NO_ASSET = -2001
final public static int INIT_ERROR_FAIL_HEAP = -2002

Description

Return a more detailed code specifying the result of the call to com.lispworks.Manager.init. The code is either one of the three INIT_ERROR_* constants above, or one of the codes that InitLispWorks returns.

INIT_ERROR_NO_LIBRARY

com.lispworks.Manager.init did not find the library.

Normally that would mean it is not in the project where it should be (libs/armeabi-v7a for Eclipse, jniLibs/armeabi-v7a for Android Studio), or its name is not correct. See deliver-to-android-project for details.

INIT_ERROR_NO_ASSET

com.lispworks.Manager.init failed to find the LispWorks heap in the assets. Normally that means that the LispWorks heap is missing from the project (it should be in assets), or its name is incorrect. See deliver-to-android-project for details.

INIT_ERROR_FAIL_HEAP

Extracting the heap from the assets failed. That in general should not happen. It may happen if the disk on the system is full.

Other values are documented for InitLispWorks. In general:

init_result_code would typically be used after com.lispworks.Manager.status returned STATUS_ERROR

When there is an error, com.lispworks.Manager.mInitErrorString contains a string describing it.

See also

com.lispworks.Manager.mInitErrorString
com.lispworks.Manager.init
com.lispworks.Manager.status
deliver-to-android-project
Delivering for Android

com.lispworks.Manager.mInitErrorString

Field

public static String mInitErrorString = ""

Description

Contains a string explaining the result for an error during initialization.

mInitErrorString is set to a non-empty string if there is an error during initialization of LispWorks, which would be detected either by using com.lispworks.Manager.status or com.lispworks.Manager.init_result_code.

The explanation is technical, so it will not be useful to show it to end users, but it should be helpful to developers, and certainly to LispWorks support.

See also

com.lispworks.Manager.init
com.lispworks.Manager.status
com.lispworks.Manager.init_result_code
Delivering for Android

com.lispworks.Manager.loadLibrary

Method

public static boolean loadLibrary()

public static boolean loadLibrary(String deliverName)

Description

Loads only the LispWorks dynamic library without initializing, for debugging.

Normally loadLibrary is called by com.lispworks.Manager.init, and in general you should not use it. It is supplied because it is sometimes useful for debugging.

com.lispworks.Manager.init can be called after loadLibrary was called, and will skip the call to it in this case.

deliverName has the same meaning as in com.lispworks.Manager.init.

Note that loadLibrary is not thread-safe on its own.

loadLibrary returns true on success, otherwise it returns false and sets com.lispworks.Manager.mInitErrorString

See also

com.lispworks.Manager.init
com.lispworks.Manager.mInitErrorString

com.lispworks.Manager.LispErrorReporter

com.lispworks.Manager.setErrorReporter

com.lispworks.Manager.LispGuiErrorReporter

com.lispworks.Manager.setGuiErrorReporter

Methods and Interfaces

public interface LispErrorReporter {
boolean report(String errorString, String filename);
}

public static void setErrorReporter(LispErrorReporter ler)

public interface LispGuiErrorReporter {
boolean report(String errorString, String filename);
}

public static void setGuiErrorReporter(LispGuiErrorReporter ler)

Description

Set error reporters that gets invoked when either report-error-to-java-host is called, or an error is not caught by your handler or hook.

setErrorReporter and setGuiErrorReporter are used to set error reporters. When either report-error-to-java-host is called (by your code, the system does not use it) or an error is not handled by your handlers (including debugger-wrappers and cl:*debugger-hook*), the report method of the interface is invoked. By default the reporters are both null.

The errorString of the report message is a string describing the error. The filename is the name of a file that contains a log file, but can be also null.

Note: when report-error-to-java-host is called it is your responsibility to pass the right strings.

The reporters should do whatever you want to do. The return value should indicate if the error was dealt with completely, so there is no need to call com.lispworks.Manager.addMessage (see below).

The reporter that is set by setErrorReporter ("the Lisp error reporter") and the reporter that is set by setGuiErrorReporter ("the Lisp GUI error reporter") differ by the scope in which their report method is invoked:

setErrorReporter and setGuiErrorReporter can be called at any time, before or after com.lispworks.Manager.init. There is only one Lisp error reporter and one Lisp GUI error reporter, and each call to setErrorReporter or setGuiErrorReporter overwrites the previous value. The reporters can be set to null.

When Lisp calls into Java to report an error, it does the following steps:

  1. If com.lispworks.Manager.mMaxErrorLogsNumber is greater than 0, records the error and delete previous record(s) if the number of records reached com.lispworks.Manager.mMaxErrorLogsNumber (these records can be displayed by com.lispworks.Manager.showBugFormLogs).
  2. If the Lisp error reporter (the non-GUI one) is not null, invoke its report method.
  3. If the Lisp GUI error reporter is not null, arrange for its report method to be invoked on the GUI process, and does the next 2 steps after this invocation.
  4. If neither of the reporters returned true, use com.lispworks.Manager.addMessage to append the error message. See documentation for com.lispworks.Manager.addMessage.
  5. If com.lispworks.Manager.mMaxErrorLogsNumber is not greater than 0, delete the log file if it is not null.
Notes

The log files are deleted when LispWorks starts (when com.lispworks.Manager.init is successful). They are also in the internal cache directory, which means they are not visible to other applications. If you want to make the logs visible, the reporter needs to copy the file to an external directory.

See also

report-error-to-java-host
com.lispworks.Manager.init
com.lispworks.Manager.addMessage
com.lispworks.Manager.showBugFormLogs
com.lispworks.Manager.mMaxErrorLogsNumber

com.lispworks.Manager.clearBugFormLogs

Method

public static synchronized void clearBugFormLogs(int count)

Description

Clear the bug form logs list.

LispWorks keeps a record of error reports containing the error strings and the file names containing the log (the arguments the report method of com.lispworks.Manager.LispErrorReporter received). clearBugFormLogs eliminates all entries except the last count entries, and removes the files.

The record is limited to com.lispworks.Manager.mMaxErrorLogsNumber, which defaults to 5.

The record can be displayed by com.lispworks.Manager.showBugFormLogs, which allows the user to open the log file of a record by selecting it.

Notes

The log files are also automatically deleted when LispWorks starts (that is when com.lispworks.Manager.init is successful).

See also

com.lispworks.Manager.setErrorReporter
com.lispworks.Manager.mMaxErrorLogsNumber
com.lispworks.Manager.showBugFormLogs

com.lispworks.Manager.mMaxErrorLogsNumber

Field

public static int mMaxErrorLogsNumber = 5

Description

Maximum number of error logs to keep.

The default value of 5 is a compromise between keeping many logs (in case some are useful) and avoiding filling the disk. During development you may want to enlarge it, and in the finished product maybe reduce it, possibly to 0.

The log files are deleted when LispWorks is initialized.

com.lispworks.Manager.showBugFormLogs

Method

public static void showBugFormLogs(Activity act)

Description

This method is for debugging.

showBugFormLogs shows a list of the BugFormLogs, where each item is an error string, and allows you to open the associated log file by touching the item. If there is only one item, it opens it immediately.

The argument act is the activity that invokes the bug list.

The bug list is displayed in its own activity, com.lispworks.BugFormLogsList, and the log file is opened to another activity, com.lispworks.BugFormViewer. To make showBugFormLogs work, you must add these activities to the file AndroidManifest.xml in your project like this:

<activity android:name="com.lispworks.BugFormViewer"   android:label="Bug Form viewer"> </activity>
<activity android:name="com.lispworks.BugFormLogsList" android:label="Bug Form Logs"> </activity>

The AndroidManifest.xml of the OthelloDemo examples contains these lines. Apart from putting the activities in the AndroidManifest.xml, you should not do anything else with them.

This method shows Lisp bug forms, so is useful only for Lisp developers.

There will not be any bug form logs if there was no error, or com.lispworks.Manager.mMaxErrorLogsNumber is set to 0, in which case showBugFormLogs does nothing. It is also possible for the user error reporters (see com.lispworks.Manager.setErrorReporter) to delete the log files, so com.lispworks.BugFormViewer will fail to show it.

showBugFormLogs is useful during development. Once the application is working, you probably want to remove the activities from AndroidManifest.xml and not use showBugFormLogs.

See also

com.lispworks.Manager.mMaxErrorLogsNumber
com.lispworks.Manager.setErrorReporter
com.lispworks.BugFormLogsList
com.lispworks.BugFormViewer

com.lispworks.Manager.addMessage

com.lispworks.Manager.mMessagesMaxLength

Method and Fields

public static void addMessage(String message, int where)

public static int mMessagesMaxLength = 10000

final public static int ADDMESSAGE_RESET = 0
final public static int ADDMESSAGE_APPEND = 1
final public static int ADDMESSAGE_PREPEND = 2
final public static int ADDMESSAGE_APPEND_NO_SCROLL = 3
final public static int ADDMESSAGE_ADD = 4
final public static int ADDMESSAGE_ADD_NO_SCROLL = 5

Description

Adds a message.

The actual meaning of adding a message is either to call the message handler if it was set by com.lispworks.Manager.setMessageHandler, or put the message in the output text view if it was set by com.lispworks.Manager.setTextView, if neither the handler or the view are set, then addMessage accumulates the messages, and inserts the text next time that that com.lispworks.Manager.setTextView is called.

The operation of addMessage is first to check whether the handler is not null, and if it is call the handler with the two arguments. If the handler returns true, addMessage does not do anything else. Otherwise, if there is a textview it adds the message to it, otherwise it adds the message to its own buffer.

where needs to be one of the six ADDMESSAGE_* constants, and determines how the message is added. ADDMESSAGE_RESET causes addMessage to first clear the textview or the internal string before adding the message. ADDMESSAGE_PREPEND means adding the string at the beginning of the textview or internal string, followed by a newline. ADDMESSAGE_APPEND, ADDMESSAGE_APPEND_NO_SCROLL, ADDMESSAGE_ADD and ADDMESSAGE_ADD_NO_SCROLL all add the message to the end of the textview or internal string. ADDMESSAGE_APPEND and ADDMESSAGE_APPEND_NO_SCROLL follow the message by a newline, while the ADDMESSAGE_ADD and ADDMESSAGE_ADD_NO_SCROLL do not. ADDMESSAGE_APPEND_NO_SCROLL and ADDMESSAGE_ADD_NO_SCROLL do not scroll, while ADDMESSAGE_APPEND and ADDMESSAGE_ADD scroll the textview to make at least the top of the new message visible.

addMessage is used by LispWorks to perform the operation of send-message-to-java-host, and to report errors which are not dealt with by the error reporters. You can use it when it is useful.

The call to the handler is done on the thread on which addMessage is called, so the handler must be able to cope with being called on any thread, and needs to be thread-safe. The access to the textview or the internal string is done on the GUI thread and is thread-safe.

mMessagesMaxLength limits the length that addMessage accumulates. The length of the text that addMessage accumulates, either internally or in the TextView, is limited to the value mMessagesMaxLength (default 10000). When appending causes the length to overflow this value, addMessage removes the beginning of the old accumulated text so the total is the limited to mMessagesMaxLength. However, it does not remove part of the message itself, so calling addMessage with a string longer than mMessagesMaxLength will cause the TextView or internal string to be longer than mMessagesMaxLength (the old text would be removed completely in this case).

Compatibility notes

ADDMESSAGE_ADD and ADDMESSAGE_ADD_NO_SCROLL are new in LispWorks 7.1. In LispWorks 7.0, the ADDMESSAGE_APPEND and ADDMESSAGE_APPEND_NO_SCROLL inserted the newline before the message. If you rely on that, you may have to modify your code.

 

See also

send-message-to-java-host
com.lispworks.Manager.setErrorReporter
com.lispworks.Manager.setMessageHandler
com.lispworks.Manager.setTextView

com.lispworks.Manager.setMessageHandler

com.lispworks.Manager.MessageHandler

Method and Interface

public void setMessageHandler(MessageHandler handler) { mMessagehandler = handler }

public interface MessageHandler {
boolean handle(String message, int where);
}

Description

Sets the message handler which com.lispworks.Manager.addMessage uses.

The handler is null by default, and can be set to null.

When the handler is not null, com.lispworks.Manager.addMessage calls the handle method with its arguments. The result tells com.lispworks.Manager.addMessage whether to deal further with the string, see its reference entry for further details.

Note that the handler can be called on any thread, and needs to be thread-safe.

See also

com.lispworks.Manager.addMessage

com.lispworks.Manager.setTextView

Method

public static synchronized void setTextView(android.widget.TextView textview)

Description

Sets the textview for com.lispworks.Manager.addMessage.

The textview defaults to null and can be set to null. When it is null, com.lispworks.Manager.addMessage accumulates the message.

When setTextView is called, if there is already a textview it takes the content first and puts it in the buffer of com.lispworks.Manager.addMessage. If the new value textview is not null, it puts into it the buffer of com.lispworks.Manager.addMessage and clears the buffer. This is designed such that you can set the TextView to another TextView or to null without losing text.

The intention is that TextView makes it easy to display messages that come from Lisp. In a fully-developed product you probably want a better mechanism, by setting the message handler with com.lispworks.Manager.setMessageHandler.

There is no expectation by setTextView or com.lispworks.Manager.addMessage about the properties of the TextView except that it is possible to add text to it and delete all the text from it. You can manipulate it yourself (for example delete all the text, or all the text except the last 100 lines) while is set.

setTextView can be called on any thread, and is thread-safe. The manipulation of the TextView by com.lispworks.Manager.addMessage is always done on the GUI process,

See also

com.lispworks.Manager.addMessage
com.lispworks.Manager.setMessageHandler

com.lispworks.Manager.getClassLoader

com.lispworks.Manager.getApplicationContext

Methods

public static ClassLoader getClassLoader()

public static Context getApplicationContext()

Description

Return the application context of the context that was supplied to com.lispworks.Manager.init, and the ClassLoader associated with it.

These are utility methods that LispWorks itself uses and you may find useful. They must be called only after com.lispworks.Manager.init was called.

See also

com.lispworks.Manager.init

com.lispworks.Manager.setCurrentActivity

Method

public static void setCurrentActivity(android.app.Activity activity)

Description

Sets the current activity that can be used inside Lisp using android-get-current-activity.

The argument activity must be the current active Activity, or null. The Lisp function android-get-current-activity returns this activity.

Once the activity becomes inactive, setCurrentActivity needs to be called with null, or the new active Activity.

Notes
  1. setCurrentActivity is effectively licensing the Lisp side to raise dialogs in the current activity.
  2. Activity instances that are used in setCurrentActivity should reset it by calling it with null in their onPause method, to ensure that they are not used after they are no longer visible.
  3. Activities that allow Lisp to raise dialogs throughout their lifetime should set it on in the onResume method.
  4. If all the activities in the application set the current activity, then you do not need to reset it in the onPause method.
  5. setCurrentActivity only affects what android-get-current-activity returns. Code that gets the Activity in other way will not be affected.
See also

android-get-current-activity


LispWorks User Guide and Reference Manual - 20 Sep 2017

NextPrevUpTopContentsIndex