public class com.lispworks.Manager
The Java class com.lispworks.Manager 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.
See 16.1 Delivering for Android for details.
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 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
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
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
public static void setCurrentActivity(android.app.Activity activity) public static ClassLoader getClassLoader() public static Context getApplicationContext()
public static void setRuntimeLispHeapDir(String dir) public static void setLispTempDir(String dir) public static void setClassLoader(ClassLoader cl)
The com.lispworks.Manager class is part of the LispWorks distribution, inside the lispworks.aar 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.
context is any object of class android.content.Context. init uses it to find the application context, and hence where the LispWorks heap is.
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. In general, reporter should use com.lispworks.Manager.status to check that initializing LispWorks succeeded. Once reporter has been 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:
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 a reporter is invoked check that com.lispworks.Manager.status returns STATUS_READY, and then rely on working LispWorks.
In most applications, all you need to do it initialize LispWorks is to call init Some specialized application may need to do some configuration before calling init, which can be done using com.lispworks.Manager.setRuntimeLispHeapDir, com.lispworks.Manager.setLispTempDir or com.lispworks.Manager.setClassLoader. You should consult LispWorks support if you believe you need to use these.
com.lispworks.Manager.status
deliver-to-android-projectcom.lispworks.Manager
16.1 Delivering for Android
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
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. |
com.lispworks.Manager.init
com.lispworks.Manager.init_result_code
com.lispworks.Manager.mInitErrorString
16.1 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.
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 ( | |
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:
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
16.1 Delivering for Android
public static String mInitErrorString = ""
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
16.1 Delivering for Android
public static boolean loadLibrary()
public static boolean loadLibrary(String deliverName)
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
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.
errorString is a string describing the error and 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
public static synchronized void clearBugFormLogs(int count)
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.
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
public static int mMaxErrorLogsNumber = 5
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.
public static void showBugFormLogs(Activity act)
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.
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
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).
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 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 handler can be called on any thread, and needs to be thread-safe.
com.lispworks.Manager.addMessage
public static synchronized void setTextView(android.widget.TextView textview)
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 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
public static ClassLoader getClassLoader()
public static Context getApplicationContext()
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.
public static void setCurrentActivity(android.app.Activity activity)
Sets the current activity that can be used inside Lisp using android-get-current-activity.
activity must be the current active Activity, or null. The Lisp function android-get-current-activity returns this activity.
Once 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.
public static void com.lispworks.Manager.setRuntimeLispHeapDir(String dir)
Sets the directory that com.lispworks.Manager.init will use for the runtime heap of LispWorks.
Note: normally you should not need to use this method.
To initialize, LispWorks needs its heap (which is in the APK), to be written to disk. By default, com.lispworks.Manager.init uses a sub-directory named lispworks-system inside the directory that is specified by the dataDir field of the ApplicationInfo of the Context that is passed to com.lispworks.Manager.init (i.e. context.getApplicationInfo().dataDir). Normally you do not need to change that, but on rare occasions you may want to use another directory, and you can use setRuntimeLispHeapDir to do that.
setRuntimeLispHeapDir must be called before com.lispworks.Manager.init is called, and throws a RuntimeException if it called after com.lispworks.Manager.init.
dir must specify the full path of the directory to use. If it does not end with a slash, then setRuntimeLispHeapDir adds a slash. It then checks if the directory exists, and if not tries to create it using File.mkdirs (which may throw an exception). It also checks that it is an existing file, and throws RuntimeException if it is.
com.lispworks.Manager.init checks if the directory already contains a Lisp heap, and uses this heap if it does, which speeds up the initialization after the first one. Therefore, you cannot use a directory that may be shared with other applications, and it is better to use the same one each time.
public static void com.lispworks.Manager.setLispTempDir(String dir)
Sets the temporary directory for that LispWorks uses.
Note: normally you should not need to use this method.
The temporary directory that LispWorks uses (which you can obtain inside LispWorks by calling get-temp-directory) is normally the directory that getCacheDir returns from the Context that is passed to com.lispworks.Manager.init (i.e. context.getCacheDir()). Normally you should not change this, but on rare occasions you may want to. It is also possible to change it inside LispWorks by calling sys:set-temp-directory. setLispTempDir allows you to set it in Java before calling com.lispworks.Manager.init.
setLispTempDir must be called before com.lispworks.Manager.init, and throws a RuntimeException if it called after com.lispworks.Manager.init.
dir must specify the full path of the directory to use. If it does not end with a slash, then setLispTempDir adds a slash. It then checks if the directory exists, and if not tries to create it using File.mkdirs (which may throw an exception). It also checks that it is an existing file and throws RuntimeException if it is.
public static void com.lispworks.Manager.setClassLoader(ClassLoader cl)
Sets the ClassLoader that LispWorks uses.
Note: normally you should not need to use this method.
By default, LispWorks uses the Class Loader from the ApplicationInfo of the Context that is passed to com.lispworks.Manager.init (i.e. context.getApplicationContext().getClassLoader()). Normally you should not change that, but on rare occasions it may be useful.
setClassLoader must be called before com.lispworks.Manager.init, and throws a RuntimeException if it called after com.lispworks.Manager.init.
cl is set to be the ClassLoader that LispWorks uses. It is also returned by com.lispworks.Manager.getClassLoader.
com.lispworks.Manager.init
com.lispworks.Manager.getClassLoader
LispWorks® User Guide and Reference Manual - 01 Dec 2021 19:30:50