asruntime.mkd

   1 # SquirrelJME As A Runtime
   2
   3 ***THIS DOCUMENT IS DEPRECATED AND WILL BE REMOVED.***
   4
   5 To use the SquirrelJME library as the main supporting run-time library will
   6 require that you implement the native methods which are located in the
   7 `cc.squirreljme.runtime.cldc.asm` package. Implementing these native methods
   8 will in the result end up with a library compatible implementation of
   9 SquirrelJME.
  10
  11 # Requirements of Java ME
  12
  13 Java ME is different from Java SE and operates in a slightly different
  14 fashion. However, every conforming Java SE JVM can run Java ME programs but
  15 the same is not possible in most cases because Java ME is a subset of Java SE.
  16
  17 ## JAR Resource Lookup
  18
  19 When using `Class.getResourceAsStream()` in Java ME, there is a strict method
  20 in how resource lookup is performed. A single JAR is considered to be a single
  21 unit where resources and classes are located. A class within one unit is not
  22 able to access the resources in another unit. Class files should not be visible
  23 to this method and not accessible as resources, the reason for this is that
  24 output executables may be ROMized which would destroy the class files that
  25 executable code is derived from.
  26
  27 As an example, here is a set of two JAR files:
  28
  29  * _foo.jar_
  30    * _Foo.class_
  31    * _onlyinfoo.txt_
  32    * _inboth.txt_
  33  * _bar.jar_
  34    * _Bar.class_
  35    * _onlyinbar.txt_
  36    * _inboth.txt_
  37
  38 This would be the result of multiple `Class.getResourceAsStream()` calls from
  39 each class:
  40
  41  * `Foo` -> _onlyinfoo.txt_: Returns _foo.jar/onlyinfoo.txt_.
  42  * `Foo` -> _onlyinbar.txt_: Returns `null`.
  43  * `Foo` -> _inboth.txt_: Returns _foo.jar/inboth.txt_.
  44  * `Foo` -> _Foo.class_: Should return `null`.
  45  * `Foo` -> _Bar.class_: Should return `null`.
  46  * `Bar` -> _onlyinfoo.txt_: Returns `null`.
  47  * `Bar` -> _onlyinbar.txt_: Returns _bar.jar/onlyinbar.txt_
  48  * `Bar` -> _inboth.txt_: Returns _bar.jar/inboth.txt_.
  49  * `Bar` -> _Foo.class_: Should return `null`.
  50  * `Bar` -> _Bar.class_: Should return `null`.
  51
  52 This reason for this is that in each JAR, there is a resource called
  53 _META-INF/MANIFEST.MF_. This resource is used and looked up my programs which
  54 are MIDlets in order to obtain their application properties. It also is used
  55 by the run-time to determine what a JAR is and what it supports.
  56
  57 ## Class Loading And Lookup
  58
  59 Unlike Java SE, there are no `ClassLoaders`. Java ME operates entirely on a
  60 single two tier approach. The first tier are classes which are built-in and
  61 available to every program. The second tier are classes which are not
  62 built-in and which have been loaded dynamically from the launcher. When a
  63 class is looked up, the order is always built-in classes first. If a program is
  64 currently being executed then it may only look up classes which exist in its
  65 execution context. If two programs are loaded they are both in two different
  66 execution contexts and they cannot lookup each others classes. Thus if two
  67 JARs have the same class, it will only use the class that is in their same
  68 JAR.
  69
  70 ## Thread Starting
  71
  72 All threads including the main thread must have a `Thread` object initialized
  73 in which `Thread.__start()` is executed for the threads. This method is in
  74 the virtual machine itself and performs most of the logic needed by the
  75 library so that porting is simpler.
  76