forked from verhas/jScriptBasic
-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathconfigure.html
More file actions
144 lines (107 loc) · 12 KB
/
Copy pathconfigure.html
File metadata and controls
144 lines (107 loc) · 12 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<!--
| Generated by Apache Maven Doxia at Jan 17, 2013
| Rendered using Apache Maven Fluido Skin 1.2.1
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>jScriptBasic - jScriptBasic Project Documentation</title>
<link rel="stylesheet" href="./css/apache-maven-fluido.min.css" />
<link rel="stylesheet" href="./css/site.css" />
<link rel="stylesheet" href="./css/print.css" media="print" />
<script type="text/javascript" src="./js/apache-maven-fluido.min.js"></script>
<meta name="author" content="Peter Verhas" />
<meta name="Date-Creation-yyyymmdd" content="20120811" />
<meta name="Date-Revision-yyyymmdd" content="20130117" />
<meta http-equiv="Content-Language" content="en" />
</head>
<body class="topBarDisabled">
<div class="container-fluid">
<div id="banner">
<div class="pull-left">
<a href="http://scriptbasic.com" id="bannerLeft">
<img src="" alt="ScriptBasic for Java"/>
</a>
</div>
<div class="pull-right"> </div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<ul class="breadcrumb">
<li id="publishDate">Last Published: 2013-01-17</li>
<li class="divider">|</li> <li id="projectVersion">Version: 1.0.4-SNAPSHOT</li>
<li class="pull-right"> <a href="http://scriptbasic.com" class="externalLink" title="ScriptBasic">ScriptBasic</a>
</li>
</ul>
</div>
<div class="row-fluid">
<div id="leftColumn" class="span3">
<div class="well sidebar-nav">
<h3>Documentation for SB4J</h3>
<ul>
<li class="none">
<a href="intro.html" title="Introduction">Introduction</a>
</li>
<li class="none">
<a href="name.html" title="Name of the game">Name of the game</a>
</li>
<li class="none">
<a href="design.html" title="History and Design Goals">History and Design Goals</a>
</li>
<li class="none">
<a href="basic.html" title="Basic Language Implemented">Basic Language Implemented</a>
</li>
<li class="none">
<a href="install.html" title="Installation">Installation</a>
</li>
<li class="none">
<a href="advanced/index.html" title="Embedding API">Embedding API</a>
</li>
<li class="none">
<strong>Configuration</strong>
</li>
</ul>
<h3>Project Documentation</h3>
<ul>
<li class="collapsed">
<a href="project-info.html" title="Project Information">Project Information</a>
</li>
<li class="collapsed">
<a href="project-reports.html" title="Project Reports">Project Reports</a>
</li>
</ul>
<hr class="divider" />
<div id="poweredBy">
<script type="text/javascript" src="https://apis.google.com/js/plusone.js"></script>
<div class="g-plusone" data-href="http://www.scriptbasic.com" data-size="tall" ></div>
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
<img class="poweredBy" alt="Built by Maven" src="./images/logos/maven-feather.png" />
</a>
</div>
</div>
</div>
<div id="bodyColumn" class="span9" >
<div class="section"><h2>Configuring ScriptBasic for Java<a name="Configuring_ScriptBasic_for_Java"></a></h2><p>First of all: ScriptBasic for Java can be executed out of the box without configuration. If you want to configure security that differs from the default or program hook classes then you can configure these features in a <tt>properties</tt> file.</p><p>The name of the properties file is <tt>sb4j.properties</tt> by default and should be loadable from the classpath. If this name does not fit the installation the name itself can be defined by the System property <tt>sb4j.configuration</tt>.</p><p>The configuration file is a standard <tt>.properties</tt> file. The following sections describe the different keys and values that can be used to configure ScriptBasic for Java and the provided interpreter hook class. Hook classes provided by third parties may also access the configuration file. Their use may vary and should be looked up in the documentation of third parties. The last section of this documentation provides guidelines that third parties should follow regarding the naming of their configuration keys.</p><div class="section"><h3>Interpreter Hooks Configuration<a name="Interpreter_Hooks_Configuration"></a></h3><p>Hook classes have to be configured. By default ScriptBasic for Java does not load, instantiate and chain such classes into the interpreter. The hook classes should be configured in strict order using the keys <tt>hook.0</tt>, <tt>hook.1</tt>, ..., <tt>hook.n</tt>. The numbers should start with zero and should be continous. If there is <tt>hook.i</tt> but there is no <tt>hook.(i+1)</tt> then all possible existing <tt>hook.j</tt> configurations for all j > i will be ignored.</p><p>The hook class configured in <tt>hook.0</tt> will be instantiated and loaded first, <tt>hook.2</tt> the second and so on. Since hooks are chained into a LIFO the methods of the last hook will be first, the last but one will be the second and so on.</p><p>The value of the configuration for each key <tt>hook.i</tt> should be the fully qualified name of the class that implements the hook functionality and as such implements the interface <tt>com.scriptbasic.interfaces.InterpreterHook</tt>.</p><p>The respective line that configures the only hook class that is provided currently with the interpreter</p><div><pre>hook.0=com.scriptbasic.hooks.RunLimitHook</pre></div></div><div class="section"><h3>Method Registering<a name="Method_Registering"></a></h3><p>ScriptBasic for Java makes it possible to call static Java methods from BASIC. These methods can be registered in the BASIC program using the commands <tt>USE</tt> and <tt>METHOD</tt> or from the embedding application calling the ScriptBasic for Java static method <tt>com.scriptbasic.utility.MethodRegisterUtility.registerFunctions(Class<?>, ExtendedInterpreter)</tt>.</p><p>If you want to secure your application denying the right from the users to execute Java method callbacks from from their BASIC programs you can switch off the commands <tt>USE</tt> and <tt>METHOD</tt> using the configuration key <tt>RunLimitHook.allowJavaMethods</tt>. The value of this key has to be <tt>false</tt> to switch off these commands and the <tt>RunLimitHook</tt> interpreter hook class has to be configured. If the configuration file contains the lines</p><div><pre>hook.0=com.scriptbasic.hooks.RunLimitHook
RunLimitHook.allowJavaMethods=false</pre></div><p>the BASIC program will not be able to execute the <tt>USE</tt> and <tt>METHOD</tt> commands. When a BASIC program contains any of those commands with this configuration the hook class will throw runtime exception and this will stop the execution of the interpreter with error. Since these </p><p>Even if you totally deny the BASIC program to define methods, you can still provide static methods for the application from Java programmatically. As a matter of fact, ScriptBasic for Java itself provides some methods for the BASIC programs predefined that should be harmless. These static methods are defined in the class <tt>com.scriptbasic.utility.RuntimeUtility</tt>. If you want to switch off all these methods and render them unreachable for the BASIC program you should include the following lines into the configuration file:</p><div><pre>deny(com.scriptbasic.classification.System)=1
deny(com.scriptbasic.classification.Math)=1
deny(com.scriptbasic.classification.Constant)=1</pre></div><p>The methods are registered by the static method <tt>com.scriptbasic.utility.MethodRegisterUtility.registerFunctions(Class<?>, ExtendedInterpreter)</tt>. This method looks up all the methods in the class passed as first argument and registers those that are annotated using the annotation interface <tt>com.scriptbasic.Function</tt>. This annotation makes it possible to classify the individual methods to be registered using Java classes. The methods presented in the class <tt>com.scriptbasic.utility.RuntimeUtility</tt> are classified with the above three classes. Setting their <tt>deny</tt> value to 1 makes them forbidden to be registered and thus the BASIC programs will not see these as functions.</p><p>The annotation may specify one or more classes that classify a method. The configuration file specifies <tt>deny</tt> and <tt>allow</tt> values for these classes. The <tt>deny</tt> values are treated as negative values, the <tt>allow</tt> values are treated as positive values. These values are summed up for all the classes that a method is classified with. If the value is non negative then the method is allowed to be registered for the BASIC programs, otherwise not.</p><p>For example a method <tt>dummy()</tt> may be classified with three different classes <tt>com.scriptbasic.classification.System</tt>, <tt>com.scriptbasic.classification.Math</tt> and <tt>com.scriptbasic.classification.Constant</tt>. (Note that there is no such method, but nothing prevents a third party to provide one.) If the configuration reads</p><div><pre>deny(com.scriptbasic.classification.System)=1
allow(com.scriptbasic.classification.Math)=2
deny(com.scriptbasic.classification.Constant)=1</pre></div><p>then the method <tt>dummy()</tt> will be registered, since <tt>-1+2-1</tt> is zero. The name of any class in the configuraiton file, including the classification classes should be qualified with FQN. Any class can be a classification class, that is available on the classpath during compile and run time.</p></div><div class="section"><h3>Hook Classes Naming<a name="Hook_Classes_Naming"></a></h3><p>Interpreter hook classes are encouraged to use configuration keys that use their fully qualified class name as configuration key prefix to avoid name collision. The authors of jScriptBasic are in a privileged position to use the short name of the interpreter hook class name without the <tt>com.scriptbasic.hooks</tt> package name. </p></div></div>
</div>
</div>
<hr/>
<footer>
<div class="container-fluid">
<div class="row span16">Copyright © 2013
<a href="http://www.verhas.com">Verhas and Verhas Software Craftsmen</a>.
All Rights Reserved.
</div>
</div>
</footer>
</body>
</html>