Artifact e504ab3a20978b86eca1b8a5499aeabeaabbdb83:
- File asruntime.mkd — part of check-in [6afa5c9fe4] at 2018-11-21 04:34:12 on branch trunk — Add note for run-time information. (user: stephanie.gawroriski size: 3192)
0000: 23 20 53 71 75 69 72 72 65 6c 4a 4d 45 20 41 73 # SquirrelJME As 0010: 20 41 20 52 75 6e 74 69 6d 65 0a 0a 54 6f 20 75 A Runtime..To u 0020: 73 65 20 74 68 65 20 53 71 75 69 72 72 65 6c 4a se the SquirrelJ 0030: 4d 45 20 6c 69 62 72 61 72 79 20 61 73 20 74 68 ME library as th 0040: 65 20 6d 61 69 6e 20 73 75 70 70 6f 72 74 69 6e e main supportin 0050: 67 20 72 75 6e 2d 74 69 6d 65 20 6c 69 62 72 61 g run-time libra 0060: 72 79 20 77 69 6c 6c 0a 72 65 71 75 69 72 65 20 ry will.require 0070: 74 68 61 74 20 79 6f 75 20 69 6d 70 6c 65 6d 65 that you impleme 0080: 6e 74 20 74 68 65 20 6e 61 74 69 76 65 20 6d 65 nt the native me 0090: 74 68 6f 64 73 20 77 68 69 63 68 20 61 72 65 20 thods which are 00a0: 6c 6f 63 61 74 65 64 20 69 6e 20 74 68 65 0a 60 located in the.` 00b0: 63 63 2e 73 71 75 69 72 72 65 6c 6a 6d 65 2e 72 cc.squirreljme.r 00c0: 75 6e 74 69 6d 65 2e 63 6c 64 63 2e 61 73 6d 60 untime.cldc.asm` 00d0: 20 70 61 63 6b 61 67 65 2e 20 49 6d 70 6c 65 6d package. Implem 00e0: 65 6e 74 69 6e 67 20 74 68 65 73 65 20 6e 61 74 enting these nat 00f0: 69 76 65 20 6d 65 74 68 6f 64 73 0a 77 69 6c 6c ive methods.will 0100: 20 69 6e 20 74 68 65 20 72 65 73 75 6c 74 20 65 in the result e 0110: 6e 64 20 75 70 20 77 69 74 68 20 61 20 6c 69 62 nd up with a lib 0120: 72 61 72 79 20 63 6f 6d 70 61 74 69 62 6c 65 20 rary compatible 0130: 69 6d 70 6c 65 6d 65 6e 74 61 74 69 6f 6e 20 6f implementation o 0140: 66 0a 53 71 75 69 72 72 65 6c 4a 4d 45 2e 0a 0a f.SquirrelJME... 0150: 23 20 52 65 71 75 69 72 65 6d 65 6e 74 73 20 6f # Requirements o 0160: 66 20 4a 61 76 61 20 4d 45 0a 0a 4a 61 76 61 20 f Java ME..Java 0170: 4d 45 20 69 73 20 64 69 66 66 65 72 65 6e 74 20 ME is different 0180: 66 72 6f 6d 20 4a 61 76 61 20 53 45 20 61 6e 64 from Java SE and 0190: 20 6f 70 65 72 61 74 65 73 20 69 6e 20 61 20 73 operates in a s 01a0: 6c 69 67 68 74 6c 79 20 64 69 66 66 65 72 65 6e lightly differen 01b0: 74 0a 66 61 73 68 69 6f 6e 2e 20 48 6f 77 65 76 t.fashion. Howev 01c0: 65 72 2c 20 65 76 65 72 79 20 63 6f 6e 66 6f 72 er, every confor 01d0: 6d 69 6e 67 20 4a 61 76 61 20 53 45 20 4a 56 4d ming Java SE JVM 01e0: 20 63 61 6e 20 72 75 6e 20 4a 61 76 61 20 4d 45 can run Java ME 01f0: 20 70 72 6f 67 72 61 6d 73 20 62 75 74 0a 74 68 programs but.th 0200: 65 20 73 61 6d 65 20 69 73 20 6e 6f 74 20 70 6f e same is not po 0210: 73 73 69 62 6c 65 20 69 6e 20 6d 6f 73 74 20 63 ssible in most c 0220: 61 73 65 73 20 62 65 63 61 75 73 65 20 4a 61 76 ases because Jav 0230: 61 20 4d 45 20 69 73 20 61 20 73 75 62 73 65 74 a ME is a subset 0240: 20 6f 66 20 4a 61 76 61 20 53 45 2e 0a 0a 23 23 of Java SE...## 0250: 20 4a 41 52 20 52 65 73 6f 75 72 63 65 20 4c 6f JAR Resource Lo 0260: 6f 6b 75 70 0a 0a 57 68 65 6e 20 75 73 69 6e 67 okup..When using 0270: 20 60 43 6c 61 73 73 2e 67 65 74 52 65 73 6f 75 `Class.getResou 0280: 72 63 65 41 73 53 74 72 65 61 6d 28 29 60 20 69 rceAsStream()` i 0290: 6e 20 4a 61 76 61 20 4d 45 2c 20 74 68 65 72 65 n Java ME, there 02a0: 20 69 73 20 61 20 73 74 72 69 63 74 20 6d 65 74 is a strict met 02b0: 68 6f 64 0a 69 6e 20 68 6f 77 20 72 65 73 6f 75 hod.in how resou 02c0: 72 63 65 20 6c 6f 6f 6b 75 70 20 69 73 20 70 65 rce lookup is pe 02d0: 72 66 6f 72 6d 65 64 2e 20 41 20 73 69 6e 67 6c rformed. A singl 02e0: 65 20 4a 41 52 20 69 73 20 63 6f 6e 73 69 64 65 e JAR is conside 02f0: 72 65 64 20 74 6f 20 62 65 20 61 20 73 69 6e 67 red to be a sing 0300: 6c 65 0a 75 6e 69 74 20 77 68 65 72 65 20 72 65 le.unit where re 0310: 73 6f 75 72 63 65 73 20 61 6e 64 20 63 6c 61 73 sources and clas 0320: 73 65 73 20 61 72 65 20 6c 6f 63 61 74 65 64 2e ses are located. 0330: 20 41 20 63 6c 61 73 73 20 77 69 74 68 69 6e 20 A class within 0340: 6f 6e 65 20 75 6e 69 74 20 69 73 20 6e 6f 74 0a one unit is not. 0350: 61 62 6c 65 20 74 6f 20 61 63 63 65 73 73 20 74 able to access t 0360: 68 65 20 72 65 73 6f 75 72 63 65 73 20 69 6e 20 he resources in 0370: 61 6e 6f 74 68 65 72 20 75 6e 69 74 2e 20 43 6c another unit. Cl 0380: 61 73 73 20 66 69 6c 65 73 20 73 68 6f 75 6c 64 ass files should 0390: 20 6e 6f 74 20 62 65 20 76 69 73 69 62 6c 65 0a not be visible. 03a0: 74 6f 20 74 68 69 73 20 6d 65 74 68 6f 64 20 61 to this method a 03b0: 6e 64 20 6e 6f 74 20 61 63 63 65 73 73 69 62 6c nd not accessibl 03c0: 65 20 61 73 20 72 65 73 6f 75 72 63 65 73 2c 20 e as resources, 03d0: 74 68 65 20 72 65 61 73 6f 6e 20 66 6f 72 20 74 the reason for t 03e0: 68 69 73 20 69 73 20 74 68 61 74 0a 6f 75 74 70 his is that.outp 03f0: 75 74 20 65 78 65 63 75 74 61 62 6c 65 73 20 6d ut executables m 0400: 61 79 20 62 65 20 52 4f 4d 69 7a 65 64 20 77 68 ay be ROMized wh 0410: 69 63 68 20 77 6f 75 6c 64 20 64 65 73 74 72 6f ich would destro 0420: 79 20 74 68 65 20 63 6c 61 73 73 20 66 69 6c 65 y the class file 0430: 73 20 74 68 61 74 0a 65 78 65 63 75 74 61 62 6c s that.executabl 0440: 65 20 63 6f 64 65 20 69 73 20 64 65 72 69 76 65 e code is derive 0450: 64 20 66 72 6f 6d 2e 0a 0a 41 73 20 61 6e 20 65 d from...As an e 0460: 78 61 6d 70 6c 65 2c 20 68 65 72 65 20 69 73 20 xample, here is 0470: 61 20 73 65 74 20 6f 66 20 74 77 6f 20 4a 41 52 a set of two JAR 0480: 20 66 69 6c 65 73 3a 0a 0a 20 2a 20 5f 66 6f 6f files:.. * _foo 0490: 2e 6a 61 72 5f 0a 20 20 20 2a 20 5f 46 6f 6f 2e .jar_. * _Foo. 04a0: 63 6c 61 73 73 5f 0a 20 20 20 2a 20 5f 6f 6e 6c class_. * _onl 04b0: 79 69 6e 66 6f 6f 2e 74 78 74 5f 0a 20 20 20 2a yinfoo.txt_. * 04c0: 20 5f 69 6e 62 6f 74 68 2e 74 78 74 5f 0a 20 2a _inboth.txt_. * 04d0: 20 5f 62 61 72 2e 6a 61 72 5f 0a 20 20 20 2a 20 _bar.jar_. * 04e0: 5f 42 61 72 2e 63 6c 61 73 73 5f 0a 20 20 20 2a _Bar.class_. * 04f0: 20 5f 6f 6e 6c 79 69 6e 62 61 72 2e 74 78 74 5f _onlyinbar.txt_ 0500: 0a 20 20 20 2a 20 5f 69 6e 62 6f 74 68 2e 74 78 . * _inboth.tx 0510: 74 5f 0a 0a 54 68 69 73 20 77 6f 75 6c 64 20 62 t_..This would b 0520: 65 20 74 68 65 20 72 65 73 75 6c 74 20 6f 66 20 e the result of 0530: 6d 75 6c 74 69 70 6c 65 20 60 43 6c 61 73 73 2e multiple `Class. 0540: 67 65 74 52 65 73 6f 75 72 63 65 41 73 53 74 72 getResourceAsStr 0550: 65 61 6d 28 29 60 20 63 61 6c 6c 73 20 66 72 6f eam()` calls fro 0560: 6d 0a 65 61 63 68 20 63 6c 61 73 73 3a 0a 0a 20 m.each class:.. 0570: 2a 20 60 46 6f 6f 60 20 2d 3e 20 5f 6f 6e 6c 79 * `Foo` -> _only 0580: 69 6e 66 6f 6f 2e 74 78 74 5f 3a 20 52 65 74 75 infoo.txt_: Retu 0590: 72 6e 73 20 5f 66 6f 6f 2e 6a 61 72 2f 6f 6e 6c rns _foo.jar/onl 05a0: 79 69 6e 66 6f 6f 2e 74 78 74 5f 2e 0a 20 2a 20 yinfoo.txt_.. * 05b0: 60 46 6f 6f 60 20 2d 3e 20 5f 6f 6e 6c 79 69 6e `Foo` -> _onlyin 05c0: 62 61 72 2e 74 78 74 5f 3a 20 52 65 74 75 72 6e bar.txt_: Return 05d0: 73 20 60 6e 75 6c 6c 60 2e 0a 20 2a 20 60 46 6f s `null`.. * `Fo 05e0: 6f 60 20 2d 3e 20 5f 69 6e 62 6f 74 68 2e 74 78 o` -> _inboth.tx 05f0: 74 5f 3a 20 52 65 74 75 72 6e 73 20 5f 66 6f 6f t_: Returns _foo 0600: 2e 6a 61 72 2f 69 6e 62 6f 74 68 2e 74 78 74 5f .jar/inboth.txt_ 0610: 2e 0a 20 2a 20 60 46 6f 6f 60 20 2d 3e 20 5f 46 .. * `Foo` -> _F 0620: 6f 6f 2e 63 6c 61 73 73 5f 3a 20 53 68 6f 75 6c oo.class_: Shoul 0630: 64 20 72 65 74 75 72 6e 20 60 6e 75 6c 6c 60 2e d return `null`. 0640: 0a 20 2a 20 60 46 6f 6f 60 20 2d 3e 20 5f 42 61 . * `Foo` -> _Ba 0650: 72 2e 63 6c 61 73 73 5f 3a 20 53 68 6f 75 6c 64 r.class_: Should 0660: 20 72 65 74 75 72 6e 20 60 6e 75 6c 6c 60 2e 0a return `null`.. 0670: 20 2a 20 60 42 61 72 60 20 2d 3e 20 5f 6f 6e 6c * `Bar` -> _onl 0680: 79 69 6e 66 6f 6f 2e 74 78 74 5f 3a 20 52 65 74 yinfoo.txt_: Ret 0690: 75 72 6e 73 20 60 6e 75 6c 6c 60 2e 0a 20 2a 20 urns `null`.. * 06a0: 60 42 61 72 60 20 2d 3e 20 5f 6f 6e 6c 79 69 6e `Bar` -> _onlyin 06b0: 62 61 72 2e 74 78 74 5f 3a 20 52 65 74 75 72 6e bar.txt_: Return 06c0: 73 20 5f 62 61 72 2e 6a 61 72 2f 6f 6e 6c 79 69 s _bar.jar/onlyi 06d0: 6e 62 61 72 2e 74 78 74 5f 0a 20 2a 20 60 42 61 nbar.txt_. * `Ba 06e0: 72 60 20 2d 3e 20 5f 69 6e 62 6f 74 68 2e 74 78 r` -> _inboth.tx 06f0: 74 5f 3a 20 52 65 74 75 72 6e 73 20 5f 62 61 72 t_: Returns _bar 0700: 2e 6a 61 72 2f 69 6e 62 6f 74 68 2e 74 78 74 5f .jar/inboth.txt_ 0710: 2e 0a 20 2a 20 60 42 61 72 60 20 2d 3e 20 5f 46 .. * `Bar` -> _F 0720: 6f 6f 2e 63 6c 61 73 73 5f 3a 20 53 68 6f 75 6c oo.class_: Shoul 0730: 64 20 72 65 74 75 72 6e 20 60 6e 75 6c 6c 60 2e d return `null`. 0740: 0a 20 2a 20 60 42 61 72 60 20 2d 3e 20 5f 42 61 . * `Bar` -> _Ba 0750: 72 2e 63 6c 61 73 73 5f 3a 20 53 68 6f 75 6c 64 r.class_: Should 0760: 20 72 65 74 75 72 6e 20 60 6e 75 6c 6c 60 2e 0a return `null`.. 0770: 0a 54 68 69 73 20 72 65 61 73 6f 6e 20 66 6f 72 .This reason for 0780: 20 74 68 69 73 20 69 73 20 74 68 61 74 20 69 6e this is that in 0790: 20 65 61 63 68 20 4a 41 52 2c 20 74 68 65 72 65 each JAR, there 07a0: 20 69 73 20 61 20 72 65 73 6f 75 72 63 65 20 63 is a resource c 07b0: 61 6c 6c 65 64 0a 5f 4d 45 54 41 2d 49 4e 46 2f alled._META-INF/ 07c0: 4d 41 4e 49 46 45 53 54 2e 4d 46 5f 2e 20 54 68 MANIFEST.MF_. Th 07d0: 69 73 20 72 65 73 6f 75 72 63 65 20 69 73 20 75 is resource is u 07e0: 73 65 64 20 61 6e 64 20 6c 6f 6f 6b 65 64 20 75 sed and looked u 07f0: 70 20 6d 79 20 70 72 6f 67 72 61 6d 73 20 77 68 p my programs wh 0800: 69 63 68 0a 61 72 65 20 4d 49 44 6c 65 74 73 20 ich.are MIDlets 0810: 69 6e 20 6f 72 64 65 72 20 74 6f 20 6f 62 74 61 in order to obta 0820: 69 6e 20 74 68 65 69 72 20 61 70 70 6c 69 63 61 in their applica 0830: 74 69 6f 6e 20 70 72 6f 70 65 72 74 69 65 73 2e tion properties. 0840: 20 49 74 20 61 6c 73 6f 20 69 73 20 75 73 65 64 It also is used 0850: 0a 62 79 20 74 68 65 20 72 75 6e 2d 74 69 6d 65 .by the run-time 0860: 20 74 6f 20 64 65 74 65 72 6d 69 6e 65 20 77 68 to determine wh 0870: 61 74 20 61 20 4a 41 52 20 69 73 20 61 6e 64 20 at a JAR is and 0880: 77 68 61 74 20 69 74 20 73 75 70 70 6f 72 74 73 what it supports 0890: 2e 0a 0a 23 23 20 43 6c 61 73 73 20 4c 6f 61 64 ...## Class Load 08a0: 69 6e 67 20 41 6e 64 20 4c 6f 6f 6b 75 70 0a 0a ing And Lookup.. 08b0: 55 6e 6c 69 6b 65 20 4a 61 76 61 20 53 45 2c 20 Unlike Java SE, 08c0: 74 68 65 72 65 20 61 72 65 20 6e 6f 20 60 43 6c there are no `Cl 08d0: 61 73 73 4c 6f 61 64 65 72 73 60 2e 20 4a 61 76 assLoaders`. Jav 08e0: 61 20 4d 45 20 6f 70 65 72 61 74 65 73 20 65 6e a ME operates en 08f0: 74 69 72 65 6c 79 20 6f 6e 20 61 0a 73 69 6e 67 tirely on a.sing 0900: 6c 65 20 74 77 6f 20 74 69 65 72 20 61 70 70 72 le two tier appr 0910: 6f 61 63 68 2e 20 54 68 65 20 66 69 72 73 74 20 oach. The first 0920: 74 69 65 72 20 61 72 65 20 63 6c 61 73 73 65 73 tier are classes 0930: 20 77 68 69 63 68 20 61 72 65 20 62 75 69 6c 74 which are built 0940: 2d 69 6e 20 61 6e 64 0a 61 76 61 69 6c 61 62 6c -in and.availabl 0950: 65 20 74 6f 20 65 76 65 72 79 20 70 72 6f 67 72 e to every progr 0960: 61 6d 2e 20 54 68 65 20 73 65 63 6f 6e 64 20 74 am. The second t 0970: 69 65 72 20 61 72 65 20 63 6c 61 73 73 65 73 20 ier are classes 0980: 77 68 69 63 68 20 61 72 65 20 6e 6f 74 0a 62 75 which are not.bu 0990: 69 6c 74 2d 69 6e 20 61 6e 64 20 77 68 69 63 68 ilt-in and which 09a0: 20 68 61 76 65 20 62 65 65 6e 20 6c 6f 61 64 65 have been loade 09b0: 64 20 64 79 6e 61 6d 69 63 61 6c 6c 79 20 66 72 d dynamically fr 09c0: 6f 6d 20 74 68 65 20 6c 61 75 6e 63 68 65 72 2e om the launcher. 09d0: 20 57 68 65 6e 20 61 0a 63 6c 61 73 73 20 69 73 When a.class is 09e0: 20 6c 6f 6f 6b 65 64 20 75 70 2c 20 74 68 65 20 looked up, the 09f0: 6f 72 64 65 72 20 69 73 20 61 6c 77 61 79 73 20 order is always 0a00: 62 75 69 6c 74 2d 69 6e 20 63 6c 61 73 73 65 73 built-in classes 0a10: 20 66 69 72 73 74 2e 20 49 66 20 61 20 70 72 6f first. If a pro 0a20: 67 72 61 6d 20 69 73 0a 63 75 72 72 65 6e 74 6c gram is.currentl 0a30: 79 20 62 65 69 6e 67 20 65 78 65 63 75 74 65 64 y being executed 0a40: 20 74 68 65 6e 20 69 74 20 6d 61 79 20 6f 6e 6c then it may onl 0a50: 79 20 6c 6f 6f 6b 20 75 70 20 63 6c 61 73 73 65 y look up classe 0a60: 73 20 77 68 69 63 68 20 65 78 69 73 74 20 69 6e s which exist in 0a70: 20 69 74 73 0a 65 78 65 63 75 74 69 6f 6e 20 63 its.execution c 0a80: 6f 6e 74 65 78 74 2e 20 49 66 20 74 77 6f 20 70 ontext. If two p 0a90: 72 6f 67 72 61 6d 73 20 61 72 65 20 6c 6f 61 64 rograms are load 0aa0: 65 64 20 74 68 65 79 20 61 72 65 20 62 6f 74 68 ed they are both 0ab0: 20 69 6e 20 74 77 6f 20 64 69 66 66 65 72 65 6e in two differen 0ac0: 74 0a 65 78 65 63 75 74 69 6f 6e 20 63 6f 6e 74 t.execution cont 0ad0: 65 78 74 73 20 61 6e 64 20 74 68 65 79 20 63 61 exts and they ca 0ae0: 6e 6e 6f 74 20 6c 6f 6f 6b 75 70 20 65 61 63 68 nnot lookup each 0af0: 20 6f 74 68 65 72 73 20 63 6c 61 73 73 65 73 2e others classes. 0b00: 20 54 68 75 73 20 69 66 20 74 77 6f 0a 4a 41 52 Thus if two.JAR 0b10: 73 20 68 61 76 65 20 74 68 65 20 73 61 6d 65 20 s have the same 0b20: 63 6c 61 73 73 2c 20 69 74 20 77 69 6c 6c 20 6f class, it will o 0b30: 6e 6c 79 20 75 73 65 20 74 68 65 20 63 6c 61 73 nly use the clas 0b40: 73 20 74 68 61 74 20 69 73 20 69 6e 20 74 68 65 s that is in the 0b50: 69 72 20 73 61 6d 65 0a 4a 41 52 2e 0a 0a 23 23 ir same.JAR...## 0b60: 20 54 68 72 65 61 64 20 53 74 61 72 74 69 6e 67 Thread Starting 0b70: 0a 0a 41 6c 6c 20 74 68 72 65 61 64 73 20 69 6e ..All threads in 0b80: 63 6c 75 64 69 6e 67 20 74 68 65 20 6d 61 69 6e cluding the main 0b90: 20 74 68 72 65 61 64 20 6d 75 73 74 20 68 61 76 thread must hav 0ba0: 65 20 61 20 60 54 68 72 65 61 64 60 20 6f 62 6a e a `Thread` obj 0bb0: 65 63 74 20 69 6e 69 74 69 61 6c 69 7a 65 64 0a ect initialized. 0bc0: 69 6e 20 77 68 69 63 68 20 60 54 68 72 65 61 64 in which `Thread 0bd0: 2e 5f 5f 73 74 61 72 74 28 29 60 20 69 73 20 65 .__start()` is e 0be0: 78 65 63 75 74 65 64 20 66 6f 72 20 74 68 65 20 xecuted for the 0bf0: 74 68 72 65 61 64 73 2e 20 54 68 69 73 20 6d 65 threads. This me 0c00: 74 68 6f 64 20 69 73 20 69 6e 0a 74 68 65 20 76 thod is in.the v 0c10: 69 72 74 75 61 6c 20 6d 61 63 68 69 6e 65 20 69 irtual machine i 0c20: 74 73 65 6c 66 20 61 6e 64 20 70 65 72 66 6f 72 tself and perfor 0c30: 6d 73 20 6d 6f 73 74 20 6f 66 20 74 68 65 20 6c ms most of the l 0c40: 6f 67 69 63 20 6e 65 65 64 65 64 20 62 79 20 74 ogic needed by t 0c50: 68 65 0a 6c 69 62 72 61 72 79 20 73 6f 20 74 68 he.library so th 0c60: 61 74 20 70 6f 72 74 69 6e 67 20 69 73 20 73 69 at porting is si 0c70: 6d 70 6c 65 72 2e 0a 0a mpler...