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:
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 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
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 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
The com.lispworks.Manager class is part of the LispWorks distribution, inside the lispworks.jar file.
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)
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.
com.lispworks.Manager.status
deliver-to-android-project
com.lispworks.Manager
Delivering for Android
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
Return the status of LispWorks:
LispWorks started initializing but has not finished yet. Because com.lispworks.Manager.init is asynchronous, it typically returns this value.
LispWorks finished initializing.
LispWorks has not started initializing, that is before com.lispworks.Manager.init was called.
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.
com.lispworks.Manager.init
com.lispworks.Manager.init_result_code
com.lispworks.Manager.mInitErrorString
Delivering for Android
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
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.
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.
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.
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:
STATUS_READY).STATUS_INITIALIZING).STATUS_NOT_INITIALIZED).STATUS_ERROR).
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.
com.lispworks.Manager.mInitErrorString
com.lispworks.Manager.init
com.lispworks.Manager.status
deliver-to-android-project
Delivering for Android
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.
com.lispworks.Manager.init
com.lispworks.Manager.status
com.lispworks.Manager.init_result_code
Delivering for Android
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
com.lispworks.Manager.init
com.lispworks.Manager.mInitErrorString
com.lispworks.Manager.LispErrorReporter
com.lispworks.Manager.setErrorReporter
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)
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:
report method of the Lisp error reporter is invoked within the scope of the error, which also means it can be any thread. It is therefore cannot do anything related to the GUI, and needs to be runnable on any thread. In general, it should only set internal variables and return, but it may also do things like copying the log file somewhere.report method of the Lisp GUI error reporter is invoked outside the scope of the error, on the GUI thread. It is done by the event loop of the GUI thread, so it is also synchronous with respect to processing events. It can therefore safely access the GUI and perform what is needed to inform the user that an error has occurred.
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:
null, invoke its report method.null, arrange for its report method to be invoked on the GUI process, and does the next 2 steps after this invocation.true, use com.lispworks.Manager.addMessage to append the error message. See documentation for com.lispworks.Manager.addMessage.null.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.
report-error-to-java-host
com.lispworks.Manager.init
com.lispworks.Manager.addMessage
com.lispworks.Manager.showBugFormLogs
com.lispworks.Manager.mMaxErrorLogsNumber
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.
The log files are also automatically deleted when LispWorks starts (that is when com.lispworks.Manager.init is successful).
com.lispworks.Manager.setErrorReporter
com.lispworks.Manager.mMaxErrorLogsNumber
com.lispworks.Manager.showBugFormLogs
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.
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.
com.lispworks.Manager.mMaxErrorLogsNumber
com.lispworks.Manager.setErrorReporter
com.lispworks.BugFormLogsList
com.lispworks.BugFormViewer
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
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).
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.
send-message-to-java-host
com.lispworks.Manager.setErrorReporter
com.lispworks.Manager.setMessageHandler
com.lispworks.Manager.setTextView
public void setMessageHandler(MessageHandler handler) { mMessagehandler = handler }
public interface MessageHandler {
boolean handle(String message, int where);
}
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.
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,
com.lispworks.Manager.addMessage
com.lispworks.Manager.setMessageHandler
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.
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.
setCurrentActivity is effectively licensing the Lisp side to raise dialogs in the current activity. 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.onResume method. onPause method. setCurrentActivity only affects what android-get-current-activity returns. Code that gets the Activity in other way will not be affected. LispWorks User Guide and Reference Manual - 20 Sep 2017