How to build a Scripting Runtime?
Contents
How to build a Scripting Runtime?
What a new Runtime needs to 供給する:
InvocationCtx 所有物／資産／財産 始める，決める
Passing Useful data to the Script
Parameters passed to the Script
現在の Runtimes invocation Parameter support
言及／関連
Developer's Guide:
Scripting 枠組み Online API documentation:
http://枠組み.openoffice.org/scripting/EDR-IDLDocs/草案s/com/sun/星／主役にする/script/枠組み
Scripting 枠組み Website:
http://枠組み.openoffice.org/scripting
Introduction
By creating a new Scripting Runtime a developer can 追加する support for the scripting language of their choice to OpenOffice.org. The Scripting 枠組み 供給するs all the 要求するd plumbing needed to 容易にする the （軍隊などの）展開，配備, binding and invocation of scripts for an runtime. The runtime just has to 供給する the language 明確な／細部 死刑執行 環境 for the script and 遂行する／発効させる it. The 枠組み takes care of the 残り／休憩（する）.
What the Scripting 枠組み 供給するs
-
一括 and （軍隊などの）展開，配備 - 基準 way to 一括 and （軍隊を）展開する，配備する scripts in a 文書 or Office 取り付け・設備. The script 小包 is just a zip とじ込み／提出する 含む／封じ込めるing the script, supporting 資源s and a 小包-descriptor.xml とじ込み／提出する, which 含む／封じ込めるs the script 明確な／細部 （軍隊などの）展開，配備 （警察などへの）密告，告訴（状） 含むing 指名する, language, and other script language 明確な／細部 所有物／資産／財産s.
-
This 一括ing and （軍隊などの）展開，配備 support for the 現在／一般に supported Runtimes (Java and BeanShell) is 供給するd through NetBeans IDE 統合，差別撤廃 module shipped with the 枠組み.
-
For other Runtimes not shipped with the 枠組み and with no 統合するd IDE support, developers can use the 命令（する） line 道具s which have been 供給するd [ 許すs a 使用者 to create a script 小包 and （軍隊を）展開する，配備する it, 関わりなく the language used].
-
Binding – 許すs 使用者s to 貯蔵所d a （軍隊を）展開する，配備するd script [取り付け・設備 or 文書] to a menu, 重要な or event using the 供給（する）d 割り当てる dialogs. These are 任命する／導入するd as part of the 枠組み under the 道具s/ “Script 追加する on's”/ 割り当てる ...
-
Invocation – once an 活動／戦闘 that has an associated script binding occurs, the 枠組み 扱うs the script invocation. It does the に引き続いて:
-
Parse URI - Parses the script URI
-
Check 許可s - Checks to see if the script is 蓄える／店d in a 文書 and if it has appropriate 許可s to run [for 詳細（に述べる）s 言及する to the relevent section on 安全 in the 使用者 Guide on the Scripting 枠組み Website].
-
負担 Script Info - 位置を示すs and 負担s up the （警察などへの）密告，告訴（状） which 述べるs the script and any language dependencies it might have from the script's 小包-descriptor.xml とじ込み／提出する 蓄える／店d in the 使用／適用 or 文書.
-
負担 language Runtime - From this （軍隊などの）展開，配備 （警察などへの）密告，告訴（状） the 枠組み can 接近 the appropriate language runtime singleton to run the script.
-
Invoke on Runtime - The 枠組み calls this language runtime's invoke method, passing the 初めの script URI and all of the 抽出するd script （軍隊などの）展開，配備 （警察などへの）密告，告訴（状）. This 含むs any language 明確な／細部 （警察などへの）密告，告訴（状）, such as Classpath for Java and BeanShell scripts.
-
Runtime - Once the 死刑執行 has been 手渡すd over to the language 明確な／細部 Runtime by the invoke( ) 機能（する）／行事 call, it is the runtime's 責任／義務 to 供給する the appropriate 死刑執行 環境 for the script, 負担 it and run it using the （警察などへの）密告，告訴（状） passed into it by the 枠組み. Once the script has run the Runtime will pass 支援する the return value and any errors to the 枠組み, which will pass them 支援する to the script 報知係.
-
What a new Runtime needs to 供給する:
-
Runtime – an 実施 of a Runtime 死刑執行 環境 for your scripting language, 述べるd in 詳細（に述べる） below.
|
部類 |
指名する |
Origin |
Description |
Comment |
|---|---|---|---|---|
|
Interface |
器具／実施するd by Runtime |
Runtime is an UNO 構成要素 |
要求するd by UNO when creating an UNO 構成要素. |
|
|
Interface |
器具／実施するd by Runtime |
Runtime is an UNO 構成要素 |
要求するd by UNO when creating an UNO 構成要素. |
|
|
Singleton |
|
器具／実施するd by Runtime |
Runtime must be a Singleton |
Need to 修正する the _writeRegistryServiceInfo() of the XServiceInfo service to 登録（する） the Runtime programatically as a Singleton [言及する to Singleton Support] |
|
Interface |
器具／実施するd by Runtime |
XScriptInvocation interface supports the invoke() method that is called when invoking scripts for a language. |
重要な interface which 許すs the Scripting 枠組み to invoke scripts in a language 独立した・無所属 manner |
|
|
Invoke() |
||||
|
Method |
XscriptInvocation: |
器具／実施するd by Runtime |
Returns an Any Invoke method of the XscriptInvocation interface |
Runtime 器具／実施するs this method in it's own language. It must 体制／機構 the script runtime 環境, 負担 up the script, pass any 要求するd parameters to it and 遂行する／発効させる the script. |
|
Parameter |
Invoke(): |
供給するd by 報知係 – Used by SF |
Is an OUString Consists of: |
（警察などへの）密告，告訴（状） only – Runtime does not need to do anything with it. SF will have already 解決するd the scriptURI to an actual script and 負担d up all the 関連した script （警察などへの）密告，告訴（状） the Runtime needs to invoke the script in the invocationCtx parameter passed to invoke(). The script URI can be used by the Runtime for logging or as a 重要な to （武器などの）隠匿場所 script 関係のある （警察などへの）密告，告訴（状）. |
|
Parameter |
Invoke(): |
供給するd by SF – Used by Runtime |
Is a XPropertySet |
供給するs Runtime with （警察などへの）密告，告訴（状） on the invocation 状況 of the script as a 始める，決める of 所有物／資産／財産 指名する/value pairs. The 重要な ones are 述べるd below. |
|
重要な InvocationCtx 所有物／資産／財産s |
||||
|
所有物／資産／財産 |
InvocationCtx: |
供給するd by SF – Used by Runtime |
Is a XModel |
XModel of the 現在の 文書 against which the script was invoked. Must be passed to the Script by the Runtime so the script can interact with the 現在の 文書. |
|
所有物／資産／財産 |
InvocationCtx: |
供給するd by SF – Used by Runtime |
Is a XScriptInfo |
含む／封じ込めるs all of the （警察などへの）密告，告訴（状） the Runtime needs to 体制／機構 the script runtime 環境 and to 負担 the script to 遂行する／発効させる it. |
|
|
||||
|
重要な XscriptInfo methods |
||||
|
Method |
XScriptInfo: |
供給するd by SF – Used by Runtime |
Returns OUString |
供給するs the 機能（する）／行事 指名する of the script you
are trying to invoke. |
|
Method |
XScriptInfo: |
供給するd by SF – Used by Runtime |
Returns OUString |
供給するs the Path to the script the Runtime
needs to invoke. |
|
Method |
XScriptInfo: |
供給するd by SF – Used by Runtime |
Returns XpropertySet |
Use this 所有物／資産／財産 始める，決める to 接近 language
明確な／細部 指名する/ value pairs 体制／機構 for the 明確な／細部 language Runtime
during script （軍隊などの）展開，配備. |
|
Invoke Parameters |
||||
|
Input Parameter |
Invoke(): |
供給するd by 報知係 - Optional |
Is a Sequence of Any |
Up to the Runtime to pass the input parameter
sequence の上に the script if input parameters are supported. |
|
生産（高） Parameter |
Invoke(): |
供給するd by 報知係 - Optional |
Is a Sequence of short |
Up to the Runtime to pass this 生産（高）
parameter 索引 （警察などへの）密告，告訴（状） 支援する to the 報知係 from the script. |
|
生産（高） Parameter |
Invoke(): |
供給するd by 報知係 - Optional |
Is a Sequence of Any Not supported by Java or BeanShell Runtimes. |
Up to the Runtime to pass the 生産（高）
parameter sequence 支援する to the 報知係 from the script. |
|
Return |
Invoke(): |
供給するd by Script, passed 支援する by Runtime - Optional |
Is an Any |
A script can return whatever it likes to the
Runtime, but it is up to the Runtime to 一括 this script
return up into a type that is supported by the UNO language
橋（渡しをする） that is 存在 used by the Runtime [must be a 原始の
type or an UNO type] |
UNO Language 橋（渡しをする）
There must be a supported UNO 橋（渡しをする） for the scripting language to 許す the 枠組み to make calls against this new scripting runtime. The 橋（渡しをする） will take care of all the parameter 保安官ing that needs to occur as the 枠組み makes the call to the invoke method written in the new language.
The Java and BeanShell Runtimes are supported by the 存在するing Java UNO 橋（渡しをする）. Any scripting language with a Java 実施 could use the Java UNO 橋（渡しをする）, such as Jython [Python], Jacl [Tcl/TK] andRhino [Javascript]. As other 橋（渡しをする）s become 利用できる native support could be 追加するd, for instance with the new PyUNO 橋（渡しをする）, a Python Runtime could be written in Python.
The Runtime
要求するd Interfaces
The Runtime is a normal UNO 構成要素, so it needs to support the に引き続いて interfaces [言及する to the Developer's Guide for 詳細（に述べる）s on creating UNO 構成要素s].
Interface: com.sun.星／主役にする.lang.XTypeProvider
Interface: com.sun.星／主役にする.lang.XServiceInfo
In 新規加入 to the normal 構成要素 interfaces above the Runtime must support the に引き続いて interface to 許す the 枠組み to invoke the scripts in a language 独立した・無所属 fashion:
Interface: 草案s.com.sun.星／主役にする.script.枠組み.XScriptInvocation
This interface supports one method, invoke( ), whose parameters and types are 述べるd below.
Invoke ( )
Returns: Any
Throws: IllegalArgumentException, CannotConvertException,
|
Parameter Types |
Parameters |
Description |
|
[in] string |
scriptURI |
初めの URI passed to the 枠組み |
|
[in] any |
invocationCtx |
（警察などへの）密告，告訴（状） on where the script was run from |
|
[in] sequence< any > |
aParams |
Input parameters |
|
[out] sequence< short > |
aOutParamIndex |
生産（高） parameter 索引 |
|
[out] sequence< any > |
aOutParam |
生産（高） parameters |
The に引き続いて sections 述べる the parameters to the invoke ( ) method call and how they can be used by a Runtime to 体制／機構 an 死刑執行 環境 for a script and then 負担 and run the script.
ScriptURI
The scriptURI is the 初めの script URI that was passed during the invoke.
This （警察などへの）密告，告訴（状） should not be 要求するd by a runtime as the 枠組み will have already 解決するd the script to a 明確な／細部 script and 負担d up the 詳細（に述べる）d script （警察などへの）密告，告訴（状） by the time the Runtime's invoke method is called [ 言及する to 虫垂 I for 詳細（に述べる）s on the 枠組み's 現在の 決意／決議 戦略].
If a runtime needs to parse the script URI, to 成し遂げる it's own 過程ing the scriptURI is 供給するd to 許す it to do so. The syntax of the script URI is:
script://<logical_name>['?'<query_element>('&'<query_element>)*]]
where : query_element = <word>'='<指名する>
|
Script URI Parameter |
Description |
|---|---|
|
logical_name |
論理（学）の 指名する of the script – this is the
指名する 陳列する，発揮するd to the 使用者 in the 割り当てる dialogs. It 許すs the
script writer to 明示する a more 使用者 friendly 指名する for the
script, rather than 陳列する，発揮するing the actual 機能（する）／行事 指名する to the
使用者. |
|
language |
Language the script is written in, must be a
supported runtime. |
|
機能（する）／行事 |
Actual language 明確な／細部 機能（する）／行事 指名する. |
|
場所 |
場所 where script is 蓄える／店d –
使用／適用 area [使用者 or 株] or 文書. |
Example of Script URI:
script://道具s.変える.ToEuro?
language=Java&
機能（する）／行事=com.sun.星／主役にする.beans.道具s.基準.変える.toEuro&
場所=使用者
Maybe better above/below if we use an example from the 枠組み
取り付け・設備.
In the 割り当てる dialogs the 使用者 will see the 道具s.変える.ToEuro script 指名する in the 名簿（に載せる）／表（にあげる） of 利用できる scripts when Java is the selected language and 使用者 the selected 場所. Selecting this script will 割り当てる the above script URI to the menu, 重要な or event binding as appropriate for the 割り当てる dialog invoked. It will be 蓄える／店d in the matching configuration とじ込み／提出する for later retrieval when the binding is invoked.
InvocationCtx
The invocationCtx is an 実施 of XPropertySet 体制／機構 by the 枠組み to give a Runtime 接近 both to the 状況 from which the script was invoked (the 現在の 文書) and the 詳細（に述べる）d （警察などへの）密告，告訴（状） on the script itself which a Runtime will need to 負担 and run the script (SCRIPT_INFO).
InvocationCtx 所有物／資産／財産 始める，決める
|
所有物／資産／財産 重要な |
Type |
Description |
|---|---|---|
|
DOC_REF |
XModel |
The XModel of the 現在の 文書 |
|
DOC_URI |
OUString |
The 文書 URI of the 現在の 文書 |
|
SCRIPT_INFO |
XScriptInfo |
XScriptInfo for the 解決するd script, 含む／封じ込めるing all of the data in the scripts 小包-descriptor.xml and the physical path of the script directory. |
|
DOC_STORAGE_ID |
sal_Int32 |
Used by the 枠組み - The 内部の 貯蔵 id of the script 貯蔵 created for this 文書 |
|
RESOLVED_STORAGE_ID |
sal_Int32 |
Used by the 枠組み - The 解決するd script 貯蔵 for this script, will be the same as the DOC_STORAGE_ID if the script is in the 文書, さもなければ it will point to the 使用者 or 株 貯蔵 areas. |
Accesing 所有物／資産／財産s from the invocationCtx 所有物／資産／財産 始める，決める [examples in Java]:
First get the 所有物／資産／財産 始める，決める from the invocationCtx:
XPropertySet invocationCtxPropSet =
( XPropertySet ) UnoRuntime.queryInterface( XPropertySet.class, invocationCtx );
Then get the 要求するd 所有物／資産／財産 [use one of the 所有物／資産／財産 重要なs above]:
反対する propObject = invocationCtxPropSet.getPropertyValue( <所有物／資産／財産 重要な> );
Query the returned 反対する for the 要求するd 反対する type:
typedPropObject = ( <所有物／資産／財産 Type> ) UnoRuntime.queryInterface( <所有物／資産／財産 Type>.class,
propObject );
For example to 接近 the SCRIPT_INFO 所有物／資産／財産:
反対する propObject = invocationCtxPropSet.getPropertyValue( “SCRIPT_INFO” );
scriptInfoPropObject = ( XScriptInfo ) UnoRuntime.queryInterface( XScriptInfo.class, propObject );
負担ing and running the script
The 枠組み will 解決する the script URI to a 明確な／細部 script and 負担 up the script （警察などへの）密告，告訴（状） into a XScriptInfo 反対する. This is then 始める，決める as a 所有物／資産／財産 of the invocationCtx which is passed の上に the Runtime in the Runtime's invoke ( ) method call.
This 含む／封じ込めるs the 重要な （警察などへの）密告，告訴（状） 要求するd by the Runtime to 遂行する／発効させる the script, it gives the Runtime 接近 to all of the （警察などへの）密告，告訴（状） about this 明確な／細部 script, 含むing physical 場所 and any language 明確な／細部 （警察などへの）密告，告訴（状） that the Runtime 要求するs to run the script, such as Classpath in the 事例／患者 of the Java and BeanShell runtimes.
The Runtime can 接近 the SCRIPT_INFO 所有物／資産／財産 of the invocationCtx as 述べるd above. Once it has the XScriptInfo it can use methods to get all the （警察などへの）密告，告訴（状） it needs to 負担 and run the script.
得る the XScriptInfo as 述べるd above and use the に引き続いて XScriptInfo interface methods to 接近 the 要求するd data:
|
XscriptInfo Method |
Return |
Description |
|---|---|---|
|
getLogicalName() |
OUString |
論理（学）の 指名する – 陳列する，発揮するd in the 割り当てる dialogs |
|
getDescription() |
OUString |
Description of the script, 供給するd during （軍隊などの）展開，配備 of the script – not 現在／一般に 陳列する，発揮するd in the 割り当てる dialogs. |
|
getLanguage() |
OUString |
Language script is written in. |
|
getFunctionName() |
OUString |
機能（する）／行事 指名する of the script [only 陳列する，発揮するd in the 割り当てる dialogs if t the 詳細（に述べる）s checkbox is selected]. |
|
getParcelURI() |
OUString |
Path to the script 小包 – needed to 負担 in the script source to the runtime. Scripts 蓄える／店d in the 使用／適用 are とじ込み／提出する
based URI's [とじ込み／提出する://]. 文書 scripts have their own 議定書 [vnd.sun.星／主役にする.pkg] |
|
getLanguageProperties() |
XPropertySet |
Language 明確な／細部 所有物／資産／財産s of the Script: 接近 指名する value pairs of this 所有物／資産／財産 始める，決める using the appropriate 所有物／資産／財産 重要なs for the script language [明示するd by the Runtime developer and 体制／機構 during （軍隊などの）展開，配備 of a script]. For Java and BeanShell classpath is the only 利用できる 所有物／資産／財産 重要な. |
|
getFileSetNames() |
Sequence of OUString |
Get a sequence of とじ込み／提出する 始める，決める 指名するs from the script 小包. The とじ込み／提出する 始める，決める 許すs the script developer to group a 始める，決める of 関係のある とじ込み／提出するs together which either the Runtime or the script can use. For instance this may be useful in 明示するing a 始める，決める of 関係のある 資源s for a script. 現在／一般に these methods are not used by the Java or BeanShell runtimes [関係のある とじ込み／提出するs/ 資源s are 一般に in jar とじ込み／提出するs that can be 明示するd on the language 所有物／資産／財産 - Classpath] |
|
getFilesInFileSet( const ::rtl::OUString & fileSetName ) |
Sequence of OUString |
Get a 名簿（に載せる）／表（にあげる） of the とじ込み／提出するs for the given fileset.
|
Typically the （警察などへの）密告，告訴（状） in the invocationCtx and ScriptInfo （警察などへの）密告，告訴（状） is used as follows by a Runtime [公式文書，認める: though 明確な／細部 to the Java and BeanShell Runtimes, the general 論理（学）の flow will be the same for most Runtimes]
Runtime Invocation
-
得る the XScriptInfo from the invocationCtx's SCRIPT_INFO 所有物／資産／財産
-
接近 the language 所有物／資産／財産s using the XScriptInfo->getLanguageProperties( ) method and 体制／機構 what ever language 明確な／細部 features are 要求するd for this runtime. For Java and BeanShell this is the Classpath.
-
For Java and BeanShell you must also 追加する the 場所 of the script to the Classpath. 得るd from the XScriptInfo getParcelURI( ) method.
-
-
体制／機構 the ScriptContext to pass to the script. In Java and BeanShell the ScriptContext is 体制／機構 as a convenience for the script developer [言及する to “Passing useful data to the Script” below].
-
Get the XComponentContext from the 構成要素 状況 passed into the Runtime's 建設者 by UNO [言及する to Developer's Guide].
-
Get the desktop using this 構成要素 状況's service factory to create an instance of the desktop service (“com.sun.星／主役にする.でっちあげる，人を罪に陥れる.desktop”) [ 言及する to Developer's Guide].
-
Get the XModel for the 現在の 文書 from the invocationCtx's DOC_REF 所有物／資産／財産.
-
-
体制／機構 the Input Parameters to pass to the script.
-
現在／一般に this is only done in Java, they are ignored in the BeanShell Runtime.
-
-
負担 up the script into the Runtime 環境.
-
In Java this is done by 負担ing up the appropriate Java Class with a matching method 署名 from the Classpath 体制／機構 above using a custom URLClassLoader [this 扱うs 負担ing both from the とじ込み／提出する system class とじ込み／提出するs, jar とじ込み／提出するs and OpenOffice.org 文書s using a custom UCB stream handler – 言及する to 接近ing 文書 Scripts below ].
-
In BeanShell the script is 負担d from the 場所 given by 連合させるing the 生産（高） of the XscriptInfo's getParcelURI() and the getFunctionName() methods. If the script is in a 文書 then it is 負担d using the custom UCBStreamHandler to create a suitable URL input stream for the eval() method of the BeanShell interpreter. さもなければ it is 負担d into the BeanShell interpreter from the とじ込み／提出する system using the source() method.
-
-
Invoke the Script – having 体制／機構 the appropriate 環境 for the script, 組み立てる／集結するd some useful （警察などへの）密告，告訴（状） for the script and 得るd 接近 to the script source, either on the とじ込み／提出する system or in a 文書, the Runtime can now invoke the script in whatever language 扶養家族 way appropriate.
-
In Java invoke the method 体制／機構 in the Script Proxy 反対する, 生成するd using the custom Classloader.
-
In BeanShell invoke using the interpreter's eval method for a 文書 script or interpreter method if 取引，協定ing with a script 蓄える／店d on the とじ込み／提出する system.
-
Passing Useful data to the Script
It is up to the Runtime to decide what （警察などへの）密告，告訴（状） to pass to a running script. It makes sense to pass （警察などへの）密告，告訴（状） to the script which makes the script writer's 職業 easier, such as a 言及／関連 to the 現在の 文書 (利用できる from the invocationCtx), 言及／関連 to the service 経営者／支配人 (利用できる from the 構成要素 状況 passed into the Runtime 構成要素's 建設者 by UNO) and a 言及／関連 to the desktop (利用できる from UNO using this service 経営者／支配人).
In both the Java Runtime and the BeanShell runtime this 状況 （警察などへの）密告，告訴（状） is made 利用できる to the running script in the form of a XScriptContext. This 供給するs accessor methods to get the 現在の 文書, the 現在の desktop and the 構成要素 状況. In the Java Runtime it's passed as the first parameter to the script and in the Beanshell Runtime it's 体制／機構 in the runtime 環境 variable, “状況”.
Interface: 草案s.com.sun.星／主役にする.script.枠組み.runtime.XScriptContext
|
XscriptContext Method |
Returns |
Description |
|---|---|---|
|
getDocument |
XModel |
接近 to the 現在の 文書. |
|
getDesktop |
XDesktop |
接近 to the 現在の desktop. |
|
getComponentContext |
XComponentContext |
Can be used by the script to get the default multi 構成要素 factory to create other UNO services. |
負担ing Scripts
Scripts can be 負担d from the 使用者 or 株 使用／適用 directories or from a 文書. The parcelURI which 供給するs the path to the script to 負担 is in the form of an encoded URI. When the Runtime is using the parcelURI to 負担 a script the Runtime needs to take account of this fact and 過程 the parcelURI 適切な before it it is used.
If you use the UNO UCB API, such as the XSimpleFileAccess, then you do not need to alter the encoded URI at all. If you want to use it to 負担 the script just append a 今後 削除する before appending the appropriate script filename and pass it to the appropriate XSimpleFileAccess methods.
The Java and BeanShell Runtimes use XSimpleFileAccess [openFileRead(), getSize()] and XInputStream [readBytes() and closeInput()] to read in the script and 体制／機構 a byte array input stream to the 文書 script. This in turn is used to create a custom stream handler that can then be used with both the ClassLoader and URL classes, to 許す the Runtimes to 負担 up classes and scripts from the 文書. Any Java based Runtime can use the helper classes in UCBStreamHandler.java and PathUtils.java.
The parcelURI is in an encoded URL 判型.. The specification for URLs, RFC 1738 : http://www.rfc-editor.org/rfc/rfc1738.txt, 限界s the use of 許すd characters in URLs to a subset of the US-ASCII character 始める，決める. For a URL to be a 井戸／弁護士席 formed URL conformant with the URL specification it must encode any characters in the URL which 落ちる outside this 限られた／立憲的な 始める，決める. URL encoding of a character consists of a "%" symbol, followed by the two-digit hexadecimal 代表 (事例／患者-insensitive) of the ISO-Latin code point for the character. Characters which need to be encoded 含む; ASCII 支配（する）／統制する characters, 非，不，無 ASCII characters, reserved characters [明確な／細部 to URL syntax 含むing Backslash (%5C) ] and 危険な characters [optional but may 原因（となる） problems in a URL, 含むing Space (%20) and 今後 削除する (%2F)].
The に引き続いて （米）棚上げする／（英）提議する 輪郭（を描く）s what is passed to the Runtime for a given 使用／適用 or 文書 script. It shows the type of 過程ing that needs to be carried out before using the parcelURI to create a 十分な path to 接近 the 使用／適用 script from the とじ込み／提出する system or the 文書 script from the 文書 [The example uses the BeanShell Runtime, but the 主要な／長／主犯's are the same for any Runtime].
|
ParcelURI: 使用／適用 Script |
|
|
ScriptURI – 過程d by the SF |
script://MemoryUsage.BeanShell?language=BeanShell&機能（する）／行事=memusage.bsh&場所=使用者 |
|
ParcelURI – passed into the Runtime |
Unix: とじ込み／提出する:///apps%20and%20utilities/staroffice/使用者/Scripts/java/MemoryUsage Windows: とじ込み／提出する:///C:/apps%20and%20utilities/staroffice/使用者/Scripts/java/MemoryUsageThe ParcelURI is passed into the Runtime in the invocationCtx's SCRIPT_INFO 所有物／資産／財産 始める，決める and 接近d using the XScriptInfo getParcelURI() method. |
|
十分な path of Script to 負担 – using UCB XSimpleFileAccess |
Unix: とじ込み／提出する:///apps%20and%20utilities/staroffice/使用者/Scripts/java/MemoryUsage/memusage.bsh Windows: とじ込み／提出する:///C:/apps%20and%20utilities/staroffice/使用者/Scripts/java/MemoryUsage/memusage.bsh < ParcelURI>/< 機能（する）／行事 指名する> |
|
|
|
|
ScriptURI |
script://MemoryUsage.BeanShell?language=BeanShell&機能（する）／行事=memusage.bsh&場所=文書 |
|
ParcelURI – passed into the Runtime |
Unix: vnd.sun.星／主役にする.pkg://とじ込み／提出する:%2F%2F%2Fscriptdev%2Fjohnr%2Fstaroffice644m5%2F使用者%2FScripts%2Fjava%2FMemoryUsage%2FExampleSpreadSheet.sxc/Scripts/java/MemoryUsage Windows: vnd.sun.星／主役にする.pkg://とじ込み／提出する:%2F%2F%2FC:%2Fscriptdev%2Fjohnr%2Fstaroffice644m5%2F
文書 URI 議定書 is vnd.sun.星／主役にする.pkg The Runtime should check for this string to see if it
should be 扱うd as an embedded 文書 script. |
|
十分な UCB path of Script to 負担 – created by the Runtime |
vnd.sun.星／主役にする.pkg://とじ込み／提出する:%2F%2F%2Fscriptdev%2Fjohnr%2Fstaroffice644m5%2F使用者%2FScripts%2Fjava%2FMemoryUsage%2FExampleSpreadSheet.sxc/Scripts/java/MemoryUsage/memusage.bsh <過程d ParcelURI>/< 機能（する）／行事
指名する> |
Parameters passed to the Script
Java Runtime
To run a Java script in OpenOffice.org, you must create a public Java class with at least one public Java method that takes an XScriptContext as it's first parameter. If no such method 存在するs the Runtime will throw an exception.
BeanShell Runtime
BeanShell scripts are 選び出す／独身 .bsh とじ込み／提出するs, there are no parameter 必要物／必要条件s when running BeanShell scripts. The Runtime does make the XScriptContext 利用できる in the BeanShell 環境, but the script can use or ignore it as it sees fit.
現在の Runtimes invocation Parameter support
|
Runtime |
Input Parameters |
生産（高） Parameters |
Return |
|---|---|---|---|
|
Java |
Supported |
Ignored |
Supported |
|
BeanShell |
Ignored |
Ignored |
Supported |
枠組み invocation Parameter support
The 枠組み scripts can be invoked either 直接／まっすぐに using a call to XFunction, 得るd from a 都合よく 建設するd XFunctionProvider or 間接に using one of the XFispatch methods.
Interface: com::sun::星／主役にする::でっちあげる，人を罪に陥れる::XDispatch
Interface: 草案s::com::sun::星／主役にする::script::枠組み::provider::XFunctionProvider
The appropriate 派遣（する） handler will be invoked for the 枠組み, based on the 議定書 of the scriptURI passed in [The Script 枠組み 議定書 handler, com.sun.星／主役にする.comp.ScriptProtocolHandler, is 登録（する）d in the ProtocolHandler.xcu configuration とじ込み／提出する when the 枠組み is 任命する／導入するd and 扱うs URI's for the “script://” 議定書].
|
Interface / Method |
Input Parameters |
生産（高） Parameters |
Return |
|---|---|---|---|
|
XDispatch: 派遣（する）( ) |
Supported |
Ignored |
Ignored |
|
XDispatch: dispatchWithNotification( ) |
Ignored |
Supported 経由で XDispatchResultListener |
|
|
XFunction: invoke( ) |
Supported |
Supported |
Supported |
Input Params
If a script is invoked from a menu, 重要な or event binding 体制／機構 using the 割り当てる dialogs, there is no way to pass an input parameter to the script . However, it is possible to pass input parameters to a script if you invoke it from another script using either the XDispatch [asynchronous] or XFunction [synchronous] interfaces as shown below:
Example using XFunction to Invoke a Script. with several input parameters
Sub DisplayEuroConversionRates ( conversionRatesRile as String, numConversions as integer)
薄暗い args(0)
args(0) = ThisComponent
' Create your FunctionProvider and 得る a Script 機能（する）／行事 from it.
FuncProvider = createUnoService(“草案s.com.sun.星／主役にする.script.枠組み.provider.FunctionProvider”)
FuncProvider.initialize( args() )
Func = FuncProvider.getFunction( “script://道具s.変える.DisplayEuroRates?_
language=Java&機能（する）／行事=com.sun.星／主役にする.beans.道具s.基準.変える.displayEuro&場所=使用者”)
薄暗い inArgs(1)
薄暗い outArgs()
薄暗い outIndex()
' 体制／機構 Input Param arguments
inArgs(0) = conversionRatesFile
inArgs(1) = numConversions
result = Func.invoke( inArgs(), outIndex(), outArgs() ) // Out params not 扱うd by Java or BeanShell
End Sub
Example using XDispatch to Invoke a Script with several input parameters
sub DisplayEuroConversionRates( conversionRatesFile as String, numConversions as integer)
薄暗い url as new com.sun.星／主役にする.util.URL
文書 = ThisComponent.CurrentController.でっちあげる，人を罪に陥れる
parser = createUnoService(“com.sun.星／主役にする.util.URLTransformer”)
薄暗い args1(1) as new com.sun.星／主役にする.beans.PropertyValue
' 体制／機構 Input Param arguments
' 公式文書，認める: args1(x).指名する can be left blank
' 始める，決める argsl(x).指名する to “Referrer” if you do not want it 追加するd as an input param
args1(0).Value = conversionRatesFile
args1(1).Value = numConversions
url.完全にする = “script://道具s.変える.DisplayEuroRates?_
language=Java&機能（する）／行事=com.sun.星／主役にする.beans.道具s.基準.変える.displayEuro&場所=使用者”
parser.parseStrict(url)
disp = 文書.queryDispatch(url,“”,0)
disp.派遣（する）(url, args1()) 'No 接近 to Out params
End Sub
生産（高） Params
Are 現在／一般に not supported in the Java and BeanShell Runtimes. If you do 器具／実施する them in your Runtime, the XDispatch script 議定書 handler has no way to 過程 them [supports one way call only]. You would only be able to 過程 them if you use the XFunction interface above in the calling script.
Returns
The script runtime can return the result of the script in an Any if it makes sense to do so. The return result must be a type that is supported by the UNO language 橋（渡しをする） 存在 used by the Runtime [一般に a 原始の type or an UNO type]. If an unsupported type is passed 支援する by the script the UNO 橋（渡しをする） will 原因（となる） an 主張する. Both the Java and BeanShell runtimes pass 支援する the return value of scripts they invoke, it is the 責任／義務 of the script writers to return types supported by the UNO 橋（渡しをする） [言及する to the Developer's Guide].
If there is no return value or the Runtime chooses not to support return values from scripts, it must always return a 無効の Any [created as follows in Java: new Any(new Type(), null);]
Errors
If any problems arise in the Runtime the に引き続いて exceptions can be thrown by the invoke call. The Runtime should make sure the errors raised match the meaning of the the exceptions given below.
|
Exception |
Description |
|---|---|
|
IllegalArgumentException |
If there is no matching script 指名する. |
|
CannotConvertException |
If arguments do not match or cannot be 変えるd the those of the invokee |
|
InvocationTargetException |
If the running script throws an exception, this （警察などへの）密告，告訴（状） is 逮捕（する）d and re thrown as this exception type. |
Runtime Singleton
The Runtime must be 体制／機構 as a Singleton. The 指名する of the singleton must follow the に引き続いて 計画／陰謀:
theScriptRuntimeFor<Runtime Language>
For example for Java the singleton is 指名するd theScriptRuntimeForJava and for BeanShell it is 指名するd theScriptRuntimeForBeanShell.
This needs to be done programmatically in the _writeRegistryServiceInfo( ) method of the XServiceInfo service. In this method you need to create the appropriate singleton registry 重要な under the UNO/Singletons 重要な in the Office 登録 database in the [言及する to example below for BeanShell].
[公式文書，認める: this is an undocumented feature of 643 builds and above and is not covered in the Developer's Guide].
Singleton Registry 入ること／参加（者）:
[実施 指名する]+ "/UNO/SINGLETONS/” + [Service Module] + “.theScriptRuntimeFor<Runtime Language>”
BeanShell Example
public static boolean __writeRegistryServiceInfo( XRegistryKey regKey ) {
String impl = "com.sun.星／主役にする.scripting.runtime.beanshell.ScriptRuntimeForBeanShell$_ScriptRuntimeForBeanShell";
String serviceModule = "草案s.com.sun.星／主役にする.script.枠組み";
String service = serviceModule + ".ScriptRuntimeForBeanShell";
if (FactoryHelper.writeRegistryServiceInfo(impl, service, regKey)) {
try {
XRegistryKey newKey = regKey.createKey(
impl + "/UNO/SINGLETONS/”+ serviceModule + “.theScriptRuntimeForBeanShell");
newKey.setStringValue(service);
return true;
} catch (Exception ex) {
System.err.println("Error 登録（する）ing ScriptRuntimeForBeanShell: " + ex);
}
}
return 誤った;
}
Configuration Changes
As of 解放（する） 0.3, runtime developers also need to make a change to the OpenOffice registry. The とじ込み／提出する <Officeinstall>/株/registry/schema/org/openoffice/Office/Scripting.xcs defines the schema used to 決定する the 関係 between a runtime, eg. BeanShell, and the とじ込み／提出する 拡張s supported by that runtime, eg. .bsh. Thus developes need to bundle a Scripting.xcu とじ込み／提出する along with their UNO 一括 (see に引き続いて section). The とじ込み／提出する used for the BeanShell runtime which follows could be used as a template:<?xml 見解／翻訳／版="1.0" encoding="UTF-8"?>
<oor:node xmlns:oor="http://openoffice.org/2001/registry" xmlns:xs="http://www.w3.org/2001/XMLSchema" oor:指名する="Scripting" oor:一括="org.openoffice.Office">
<node oor:指名する="ScriptRuntimes">
<node oor:指名する="BeanShell" oor:op="取って代わる">
<支え（る） oor:指名する="SupportedFileExtensions">
<value xml:lang="en-US">bsh</value>
</支え（る）>
</node>
</node>
</oor:node>
一括ing
The new Runtime must be 一括d as an UNO 構成要素. 言及する to the Developer's Guide on 指示／教授／教育s on how to use the pkgchk 道具 to 一括 the Runtime and any 付加 資源s it may 要求する.
Creating Scripts
If you want to 許す your 使用者s to create script 小包s for the new language Runtime, you can create a 道具 to create a script 小包, or you can use the 存在するing 命令（する） line 道具s to do so.
The script 小包 is just a zip とじ込み／提出する 含む／封じ込めるing the script and any associated 資源s and a 小包-descriptor.xml とじ込み／提出する, which gives the 詳細（に述べる）s of the script, 含むing language 明確な／細部 （警察などへの）密告，告訴（状） that may be needed to run the script.
You could 令状 your own 道具s to create the 小包-descriptor.xml とじ込み／提出する. 言及する to 虫垂 I for the 小包-descriptor.xml DTD.
Binding to Scripts
If a Runtime has been 任命する／導入するd the 割り当てる dialogs will automatically （悪事，秘密などを）発見する the new language Scripting Runtime singleton. The language will then be 利用できる as a choice in the language 減少（する） 負かす／撃墜する combo of all of the 割り当てる dialogs. Choosing it the 使用者 will be 現在のd with a 名簿（に載せる）／表（にあげる） of any scripts for this language, （軍隊を）展開する，配備するd into the 明示するd 場所 [取り付け・設備 – 使用者/ 株; 文書].
The Runtime developer has nothing to do other than make sure the Runtime is 登録（する）d as a singleton using the above 指名するing 計画／陰謀.
虫垂 I
Scripting 枠組み 決意／決議
If a Script URI has all of the 重要な fields filled out [論理（学）の 指名する, language, 機能（する）／行事 and 場所] then the Script URI will be unambiguously matched to only one 肉体的に （軍隊を）展開する，配備するd script. If no match is 設立する then a Runtime exception is raised by the 枠組み.
What happens if you omit some or all of the optional fields? The 枠組み will 試みる／企てる to 解決する the Script URI to one of the （軍隊を）展開する，配備するd scripts as follows.
|
Omitted Script URI Parameter |
決意／決議 戦略 |
|---|---|
|
機能（する）／行事 |
Will search for the first match from the 名簿（に載せる）／表（にあげる） of all 利用できる 機能（する）／行事 実施s for a given 論理（学）の 指名する by alphabetical order of the 機能（する）／行事s. |
|
場所 |
Will search for the first matching script from all the 利用できる 貯蔵 場所s in the order of 文書, 使用者 and 株. |
|
language |
Will search for the first match in the 利用できる supported language Runtimes by alphabetical order of the Runtimes. |
In the 未来 it may be possible to configure the 枠組み's 決意／決議 戦略s if the Script URI is not fully qualified.
Runtime 明確な／細部 決意／決議
In some Runtime's it may
be necessary to do その上の 決意／決議 checks, based not just on the
機能（する）／行事 指名する, but also on the Parameter 名簿（に載せる）／表（にあげる） passed 負かす／撃墜する to the script.
For instance, the Java Runtime will check that the script which the
枠組み has 解決するd also matches a method with the appropriate
署名 on the 利用できる Classpath for this script and if it does not
will throw an exception.
虫垂 II
小包 Descriptor DTD and 見本 XML
Each script must 含む／封じ込める a 小包-descriptor.xml とじ込み／提出する which 供給するs all the necessary metadata for the script. The DTD for the 小包-descriptor.xml follows
<?xml 見解／翻訳／版="1.0" encoding="UTF-8"?>
<!-- DTD for 小包 Meta data for use in the OpenOffice.org Scripting 枠組み 事業／計画（する） -->
<!ELEMENT logicalname EMPTY>
<!ELEMENT description (#PCDATA)>
<!ELEMENT displayname EMPTY>
<!ELEMENT 地元の (displayname?, description?)>
<!ELEMENT functionname EMPTY>
<!ELEMENT 支え（る） EMPTY>
<!ELEMENT languagedepprops (支え（る）+)>
<!ELEMENT とじ込み／提出する (支え（る）*)>
<!ELEMENT fileset (とじ込み／提出する+)>
<!ELEMENT script (地元の+, functionname, logicalname, languagedepprops*, fileset*)>
<!ELEMENT 小包 (script+)>
<!ATTLIST logicalname
value CDATA #REQUIRED
>
<!ATTLIST displayname
value CDATA #REQUIRED
>
<!ATTLIST 地元の
lang CDATA #REQUIRED
>
<!ATTLIST functionname
value CDATA #REQUIRED
>
<!ATTLIST logicalname
value CDATA #REQUIRED
>
<!ATTLIST 支え（る）
指名する CDATA #REQUIRED
value CDATA #REQUIRED
>
<!ATTLIST とじ込み／提出する
指名する CDATA #REQUIRED
>
<!ATTLIST fileset
指名する CDATA #IMPLIED
>
<!ATTLIST script
language CDATA #REQUIRED
>
<!ATTLIST 小包
language CDATA #REQUIRED
>
The に引き続いて is an example of a 小包-descriptor.xml とじ込み／提出する that defines a script, 器具／実施するd in Java. The languagedepprops element is used to 延長する the JVM's classpath.
<?xml 見解／翻訳／版="1.0" encoding="UTF-8"?>
<!--見本 Meta Data for use with the Scripting 枠組み 事業／計画（する） in OpenOffice.org -->
<!DOCTYPE 小包 SYSTEM "小包.dtd">
<小包 language="Java">
<script language="Java">
<地元の lang="english">
<displayname value="Memory.usage"/>
<description>
陳列する，発揮するs the memory 現在の memory usage
</description>
</地元の>
<functionname value="memoryUtils.memoryUsage"/>
<logicalname value="MemoryUtils.MemUsage"/>
<languagedepprops>
<支え（る） 指名する="classpath" value="/選ぶ/foo.jar:/usr/java/src.jar"/>
</languagedepprops>
<fileset>
<とじ込み／提出する 指名する="mems.txt">
<支え（る） 指名する="type" value="資源"/>
</とじ込み／提出する>
</fileset>
</script>
</小包>
