Differences

This shows you the differences between two versions of the page.

--- at:tutorial:appendix [2008/07/10 17:21] – added tvcutsem
+++ at:tutorial:appendix [2008/07/10 17:41] – added tvcutsem
@@ Line 600: / Line 600: @@
 ==== Logging Framework ====
+The module ''/.at.support.logger'' defines a tiny logging framework akin to the well-known [[http://logging.apache.org/log4j|Log4J]] logging framework for Java.
+Here's a typical example of how to use a logger:
+<code>
+import /.at.support.logger;
+def log := makeLogger("my prefix", INFO); // do not log DEBUG
+log("a message", ERROR); // message level is optional and defaults to INFO
+</code>
+The ''makeLogger'' function returns a function which can be used to log messages to an output object. It takes three arguments, all of which are optional: a string to be prefixed to every logged message (default ''""''), a logging level (default ''DEBUG'') and an output object (default ''system'').
+The logging level determines which messages are shown on the output log. The available error levels are: ''NONE'', ''DEBUG'', ''WARNING'', ''INFO'', ''ERROR'' and ''FATAL'' in order of exceeding importance. Hence, a log whose default is ''WARNING'' will not show ''DEBUG''-level messages.
+The output object is an object that understands ''println(string)''. It is used by the logging framework to write its log to the screen, a file, etc.
 ==== Object Inspector ====
+The module ''/.at.support.inspector'' implements a graphical object inspector. The module requires ''java.awt'' and ''javax.swing'' support from the underlying JVM running AmbientTalk. To inspect an object ''o'', execute:
+<code>
+import /.at.support.inspector;
+inspect(o);
+</code>
+This will pop up a graphical inspector on the object, listing the object's fields and methods. The object's fields and methods can recursively be inspected through the graphical user interface of the object inspector.
 ==== Symbiosis Utilities ====
+The module ''/.at.support.symbiosis'' defines a number of utility functions with respect to the symbiosis with the JVM. It defines the following functions which can be used to quickly create a wrapped Java value of the given primitive type:
+<code>
+long(anAmbientTalkNumber) -> aJavaLong
+short(anAmbientTalkNumber) -> aJavaShort
+float(anAmbientTalkFraction) -> aJavaFloat
+byte(anAmbientTalkNumber) -> aJavaByte
+</code>
+The module also defines the following function:
+<code>
+cast: obj into: Interface
+</code>
+The ''Interface'' argument should be a Java class wrapper for an interface type. The function returns a Java proxy object implementing the given interface, wrapping the given AmbientTalk object. If this proxy is subsequently passed to Java code, it will hold that ''proxy instanceof Interface''.
 ==== Miscellaneous ====
+The module ''/.at.support.util'' is a utility module grouping several miscellaneous tasks.
+=== Random Numbers ===
+The utility module defines functions for easily generating random numbers. Its implementation uses the random number generators from the underlying JVM. The following functions are the most useful:
+<code>
+// generate a random integer in the interval [min, max[
+def randomNumberBetween(min, max)
+// generate a random fraction in the interval [min, max[
+def randomFractionBetween(min, max)
+</code>
+=== Custom Object Serialization ===
+The method ''uponArrivalBecome:'' exported by the utility module creates a transporter object which can be used in ''pass'' meta-level methods to execute code upon deserialization. The closure passed to this function should return the object with which the transported object should be replaced. For example:
+<code>
+//inside a mirror
+def instancevar := ...;
+def pass() {
+  uponArrivalBecome: { |instancevar|
+    // return object to become here
+  }
+}
+</code>
+The function plays a role similar to ''readResolve'' in the Java object serialization framework.