ch.hevs.kart

Class KartSequence

java.lang.Object

ch.hevs.kart.KartSequence

public class KartSequence
extends java.lang.Object

A KartSequence is a step-by-step sequence of commands that can be uploaded to a Kart.

The Kart's sequence player executes one instruction after another and supports a well defined set of opcodes along with their arguments. This class allows to generate those vm commands by exposing a simple interface to construct the sequence. Using the method Kart.run(KartSequence) the sequence can be uploaded to the kart and getting started.

The builder pattern (KartSequence.Builder) can be used in order to construct such a sequence. Sequences can be saved and loaded to/from xml files by using the methods save(java.lang.String, android.content.Context) and load(java.lang.String, android.content.Context).

IMPORTANT: This feature is experimental: This means that there might be still bugs and the sequence player might not be implemented on all Karts!

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	KartSequence.Builder Builder which has to be used in order to construct new KartSequences.
static class	KartSequence.Instruction Instruction class, represents a single instruction (opcode + operand).

Constructor Summary

Constructors

Constructor and Description
KartSequence()

Method Summary

Modifier and Type	Method and Description
void	addInstruction(KartSequence.Instruction.OpCode opcode, short operand) Adds a new instruction with the given opcode and operand to the end of the sequence.
void	addInstruction(KartSequence.Instruction instruction) Adds the given instruction to the end of the sequence.
static java.lang.String[]	availableSequences(android.content.Context context) Returns a list of the available kart sequence files.
static KartSequence.Builder	Builder() Creates and returns a new Builder in order to construct a Kart sequence.
KartSequence.Instruction	getInstruction(int index) Returns a reference to the instruction at the given index in order to modify the instruction or null if the index is outside the sequence bounds.
void	insertInstruction(int index, KartSequence.Instruction.OpCode opcode, short operand) Adds a new instruction with the given opcode and operand to the given index of the sequence.
void	insertInstruction(int index, KartSequence.Instruction instruction) Adds the given instruction to the given index of the sequence.
static KartSequence	load(java.lang.String filename, android.content.Context context) Tries to load a kart sequence from the given XML file.
static KartSequence	loadFromBundle(android.os.Bundle bundle) Tries to load a kart sequence from the given bundle.
void	removeInstruction(int index) Removes the instruction at the given index from the sequence.
void	save(java.lang.String filename, android.content.Context context) Saves the sequence as XML file inside the application's private data location.
void	saveToBundle(android.os.Bundle bundle) Saves the sequence to the given bundle.
int	size() Returns the number of instructions in the sequence.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

KartSequence

public KartSequence()

Method Detail

Builder

public static KartSequence.Builder Builder()

Creates and returns a new Builder in order to construct a Kart sequence. See the KartSequence.Builder documentation for available commands a sequence can be made of.

Returns:

New KartSequence Builder.

size

public int size()

Returns the number of instructions in the sequence.

Returns:

Number of instructions.

getInstruction

public KartSequence.Instruction getInstruction(int index)

Returns a reference to the instruction at the given index in order to modify the instruction or null if the index is outside the sequence bounds.

Parameters:

index - Index of the instruction in the sequence.

Returns:

Reference to the instruction.

addInstruction

public void addInstruction(KartSequence.Instruction.OpCode opcode,
                           short operand)

Adds a new instruction with the given opcode and operand to the end of the sequence.

Parameters:

opcode - Instruction's opcode.

operand - Instruction's operand.

addInstruction

public void addInstruction(KartSequence.Instruction instruction)

Adds the given instruction to the end of the sequence.

Parameters:

instruction - Instruction to add to the end of the sequence.

insertInstruction

public void insertInstruction(int index,
                              KartSequence.Instruction.OpCode opcode,
                              short operand)

Adds a new instruction with the given opcode and operand to the given index of the sequence. Shifts the instruction currently at that position and any subsequent elements downwards.

Parameters:

index - Index at which the instruction has to be inserted.

opcode - Instruction's opcode.

operand - Instruction's operand.

insertInstruction

public void insertInstruction(int index,
                              KartSequence.Instruction instruction)

Adds the given instruction to the given index of the sequence. Shifts the instruction currently at that position and any subsequent elements downwards.

Parameters:

index - Index at which the instruction has to be inserted.

instruction - Instruction to insert into the sequence.

removeInstruction

public void removeInstruction(int index)

Removes the instruction at the given index from the sequence.

Parameters:

index - Index of the sequence to remove.

save

public void save(java.lang.String filename,
                 android.content.Context context)
          throws java.io.IOException

Saves the sequence as XML file inside the application's private data location. The suffix ".kartseq" will be added to the filename that is actually saved.

Parameters:

filename - Filename for the sequence.

context - Android context (needed to open output stream).

Throws:

java.io.IOException - If the sequence could not be serialized to the file.

load

public static KartSequence load(java.lang.String filename,
                                android.content.Context context)
                         throws java.io.IOException,
                                org.xmlpull.v1.XmlPullParserException

Tries to load a kart sequence from the given XML file. Note that the file suffix ".kartseq" is automatically added to the file name.

Parameters:

filename - File name of the sequence to load.

context - Android application context (needed to open input stream).

Returns:

Loaded kart sequence.

Throws:

java.io.IOException - Thrown if the file does not exists or is invalid.

org.xmlpull.v1.XmlPullParserException - Thrown if there was an error parsing the file's XML content.

availableSequences

public static java.lang.String[] availableSequences(android.content.Context context)

Returns a list of the available kart sequence files. Note that the file suffix is removed from the file names.

Parameters:

context - Android application context (needed to enumerate the files).

Returns:

Sequence files names that can be loaded, or an empty array if no sequence have been found.

saveToBundle

public void saveToBundle(android.os.Bundle bundle)

Saves the sequence to the given bundle.

Parameters:

bundle - Bundle to save the sequence to.

loadFromBundle

public static KartSequence loadFromBundle(android.os.Bundle bundle)

Tries to load a kart sequence from the given bundle.

Parameters:

bundle - Bundle to load the sequence from.

Returns:

Kart sequence or nil if no sequence was saved to the bundle before.