JOY Script

Stuff you probably want right now:

• Source
• Distribution
• Co(mplain)ntact author: zwei2stein@gmail.com

What is it?

JOY Script is simple framework for creating simple scripting engines

It is to be used whenever developer needs to have part of application functionality scripted rather than hardcoded. For example author of game might want to script its game logic rather than hardcode everything.

How does it work?

Developer starts by writing set of instructions he needs in his scripting language: He creates set of classes by extending Instruction class from JOY Script. To use theese new instructions in script, he only needs to add package where this class is located to scripting engine and then use this class in script - with tag name derived from class name and attributes derived from setter methods.

Then, at runtime XML is parsed and instruction are instantiated. Instantiated script is added to library from which it can be retrieved and ran at any time.

To run script, developer retrieves script from library and passes it context in which script should run, and executes it.

What else should i know?

• You can add new instructions at runtime.
• Library can be refreshed runtime. Both this allows extending features without redeploying whole application
• You can use instruction from several codebases at same time. conflicts are resolved in deterministic way. Well designed codebase will use its own context

Examples and How-Tos

Instruction example

This is example of how instructions are built, here is core instruction "log"

package cz.zweistein.joyscript.instruction.instructionset;

import cz.zweistein.joyscript.SerializationTool;

 /**
  * 
  * Logs information at info level
  * 
  * @author prokop
  *
  */
public class InstructionLog extends Instruction {

	private String message;

	@Override
	protected void execute() {
		logger.info(this.message);
	}

	@Override
	public String getText(int level) {
		return SerializationTool.indent(level) +"Log: "+this.message+"\n";
	}
	
	public void setMessage(String message) {
		this.message = message;
	}

	@Override
	public Instruction cloneCode() {
		InstructionLog instruction = new InstructionLog();
		instruction.setMessage(this.message);
		return instruction;
	}

}

And here is its usage:

<scripts>

	<script id="demoScript1">
 		<log message="Hello, World!" />
	</script>
 
</scripts>

And this is code used to run this script:

GlobalContext globalContext = new GlobalContext();
Library library = new Library();
library.initScripts("xml/scripts.xml", new ArrayList<String>());
library.setGlobalContext(globalContext);
library.getScripts().getItem("demoScript1").getInstruction().run();

Cook-book for Instruction:

1. Create new class in your own package of choice. Extend abstract "cz.zweistein.jae.script.instruction.instructionsetInstruction", follow naming convention and name you class with Instruction prefix
2. Override execute method, getText method and cloneCode method. cloneCode method is vital to implement - without it instruction will never leave library.
3. If package of that instruction is not already part of subClassPath, add it.
4. add element with your instruction to source xml, element name is instruction name (without Instruction Prefix), parameters are setters which you defined.
5. Thats it, you now have working instruction!

Cook-book for applications:

1. We initialize our own class path manually
   		List subClassPath = new ArrayList();
   		subClassPath.add("org.example.ourinstructions");

2. We create our global context
   		GlobalContext globalContext = new GlobalContext();

3. We load scripts to library 
   		Library library = new Library();
   		library.initScripts("xml/scripts.xml", subClassPath);
   		library.setGlobalContext(globalContext)

4. Get our script, run it, voala!
   		Script script = library.getScripts().getItem("script");
   		script.run();

Coding tips & troubleshooting

• Create your own context to pass information (Extend user context, add instance to global context). This allows multiple different instruction families run side by side without interference.
• Dont forget to implement clone method and keep it updated
• If you have setter in instruction that is not parameter of instruction, annotate it with @NonReflectableSetter see other annotation such as @OptionalSetter to customize your parameters even further. Remeber that you are not confined to String values @ObjecTInstanceSetter allows earch parameter have its factory.
• There are two types of instructions: With and without Children. Instruction without Children is plain line of code - statement, while instruction with children is control structure - i.e. if or while.

Thats all for now.