err.no Git - sope/blob - Recycler/NGJavaScript/README

   1 # $Id$
   2
   3 Objective-C / JavaScript bridge
   4 ===============================
   5
   6 This code implements an Objective-C/JavaScript bridge that uses the
   7 SpiderMonkey JavaScript engine from the Mozilla project. It's used
   8 for scripted NGObjWeb components and for SKYRiX forms.
   9
  10 It works pretty well so far, but currently requires a bit of work
  11 to expose functions and properties from ObjC to JavaScript. Note that
  12 it's by intention that not all selectors of an ObjC class are exposed
  13 automatically as JavaScript functions primarily for security reasons
  14 (we want to support JavaScript 'sandboxes').
  15
  16 In later versions I would like to move to mapping code to a configuration
  17 file and maybe add some security assertions. Pretty much like the Zope
  18 security system ... I'm not sure yet how/whether we could use the builtin
  19 security principal objects of SpiderMoneky.
  20 Further the bridge could/should get more AppleScript API like, that is,
  21 it should build scriptClassDescriptions and maybe use the Foundation
  22 ValueCoercionHandler.
  23
  24 The bridge is not thread safe in the moment. At least one thing: the
  25 current mapping context is stored in a global variable.
  26
  27 TRAPS:
  28 ======
  29   - do never use things as properties which reference the property owner, since
  30     properties are cached by SpiderMonkey, you are going to have a cycle. Eg:
  31
  32       dom.all['blah']
  33
  34     If the 'all' proxy retains the 'dom' object, we are going to have a cycle.
  35     'all' may only have a weak reference to 'dom' !
  36     => this could be improved now be using the new deallochack from
  37        MulleKybernetik
  38     => Brendan Eich also added some kind of pass-through flag were a backend
  39        class can be the only property store and therefore disable the
  40        described caching ?
  41
  42 Archiving
  43 =========
  44
  45 See archiving in Rhino to understand the difficulties:
  46
  47   http://mozilla.org/rhino/serialization.html
  48
  49 NSArchiver makes some things easier by providing conditional
  50 archiving. Eg the prototype and parent object are encoded that
  51 way. Besides that the mapping context is never encoded - you need
  52 to create one before you unarchive JS objects.
  53
  54 Currently function objects are never archived. To be fixed.
  55
  56 BUGS
  57 ====
  58
  59 - objectForKey:functionName does not return a NGJavaScriptFunction ?
  60 - during large exports with SkyPublisher either the bridge or SpiderMonkey
  61   sometimes dump core in some AddRootObject call
  62 - function objects are not archived
  63
  64 TODO
  65 ====
  66
  67 - we should probably create one JS class for each Objective-C
  68   class, so that we don't need to define all the hooks again
  69   and again (but instead use the class prototype object) !
  70   (needs to be recreated if bundles are loaded)
  71 - BUGS first ! ;-)
  72 - speed, NGJavaScript currently is not optimized at all
  73 - thread safety
  74 - better AppleScript class compatibility
  75 - improved mapping facilities (mapping rule files)
  76 - archiving of additional native objects (dates, functions, ...)
  77 - combined objects
  78 - add dealloc-hack to improve tracking of objects
  79
  80 Internals
  81 =========
  82
  83 NGJavaScript is based on the NGScripting library which already provides
  84 the high-level API to load and execute scripts in any language.
  85
  86 Classes
  87   NGJavaScriptObject
  88
  89   NGJavaScriptArray
  90   NGJavaScriptArray(NSArrayCompatibility)
  91   NGJavaScriptArray(NSMutableArrayCompatibility)
  92   - a JavaScript array. this class inherits from NGJavaScriptObject
  93     and "aquires" the methods of NSMutableArray using add_behaviour,
  94     which is unsupported on NeXT runtime
  95
  96   NGJavaScriptCallable
  97   - a JavaScript "callable", that is, a JavaScript function or method
  98
  99   NGJavaScriptContext
 100   NGJavaScriptFunction
 101   NSObject(JSFuncTyping)
 102   NGJavaScriptLanguage
 103   NGJavaScriptObjCClassInfo
 104   JSIDEnum
 105   JSObjChainEnum
 106   NGJavaScriptObjectHandler
 107   NGJavaScriptObjectMappingContext
 108   NGJavaScriptObjectMappingContext(CombinedObjects)
 109   NSObject(JSCombinedObjects)
 110   JSCombinedObjectBehaviour
 111   NGJavaScriptRuntime
 112   NGJavaScriptShadow
 113
 114 Some JS Samples
 115 ===============
 116
 117   Exception Handling:
 118     throw myObject;
 119     try {} catch (localException) { };
 120     - localException is the exception itself, not a switch on
 121       it's class
 122     - throw can take any object, eg: "throw 5"
 123
 124 Defaults
 125 ========
 126
 127   JSAbortOnError        (abort on "JS ERROR" logs)
 128   JSDebugContextDealloc (enable some logs in -dealloc of the JS Context Wrap)
 129   jsLogPropDef         bool
 130   jsLogFuncDef         bool
 131   JSLogHandleForObject bool  log calls to -handleForObject:
 132   JSLogValueConversion bool  log calls to jsValue:forObject: