SQLSpaces Shell

[back]

For people that are familiar with the Bourne-again Shell (bash) or similar shells, SQLSpaces offers a console interface with its typical advantages and disadvantages: On the one hand it is right now the most powerful and expressive way to use the SQLSpaces in an interactive way, but on the other hand it is not a colourful, clickable and easy to learn and understand interface. If this does not shock you, you will like it :)

The sssh tries to adapt as many concepts and commands from the bash and the windows console as possible to make the migration easier. This comprises a bash-like command prompt that shows the user the current "position", a similar notion of "folders" (that are in this case the different subspaces and signatures), and last but not least also similar commands. To make it easy for Linux users as well as for Windows users there are several commands that have aliases (like "ls" and "dir", "rm" and "del").

[top]

How to use it

The shell uses a socket connection that just sends plain ASCII string over the line, just like telnet. Therefore, you have to have access to the port the shell server is running (default: 2540).

As soon as the server is running, there are three ways to access the shell. The easiest is by using it in the web interface. As soon as you have deployed the web module WAR, you have not only access to the Investigator and the Vizard, but also to the sssh. Just click on "shell" in the title bar and you will have a web-based shell on that server.

Another possibility is to use a common telnet client. Since the communication is very similar to the telnet way, the telnet clients that are shipped with your OS should be able to speak to the sssh server (tested with Windows and Linux). Therefore, just enter in the console something like "telnet localhost 2540".

The last way of using the shell is to use our included shell executable. This is for people, who do not have any telnet client at hand, who do not use the integrated webserver or that need some more "shell convenience" like auto-completion or browsing through a command history. This more convenient sssh client is distributed in a seperate ZIP bundle that needs to be extracted before usage. In the main folder of this ZIP, you'll find an executable for Unix and Windows machines. To be able to call this executable from every location, it is advised to create a (sym)link to that file at some place in the PATH variable.

Please note: Internally all three ways use the same underlying protocol and therefore need access to the shell port.

[top]

Navigating

Depending on the "location" the notion of a folder is different. After the connection you start in the root folder "/", which has all the spaces as subfolders. The commands to show the folders are ls and dir. To select a space, just enter cd <spacename>. The prompt will turn from "/" to "/spacename" to indicate this selection. If you have selected a space by cd the folders that can now be seen via ls or dir are the signatures of all tuples written to this space. Please note that this is already the final level of the folder structure, i.e. you cannot cd into a signature. The typical cd .. will of course let you go back in the folder hierarchy.

[top]

Reading, Writing and Deleting Tuples

Before accessing the tuples in the shell, you have to understand how tuples are encoded. There are a few simple rules for that:

  • Fields are separated by an underscore ("_").
  • Formal fields are encoded by their "names". A valid signature would be: String_Integer_Binary_XML
  • Actual fields are encoded by their values, strings are enclosed by double quotes, chars by single quotes and numbers can be type-specified, e.g. "Test"_1_3d_true
  • Wildcard fields are "*", inverse fields start with a "!", semiformal fields contain "*" in a string, e.g. "stefan*"_"!login successful"_*
  • If any of the special characters ("*", !, _, \) should appear as a part of a string, they need to be escaped by "\", e.g. "omg\! I have a new \*hello kitty\* bag =^\_^="
  • If you want to address a tuple with a certain ID, you encode that by round brackets and the ID, e.g. (12345)

In general the operations read, write and take are mapped to their equivalents in the console world. To read the content of a space, use ls or dir. Without any parameter these commands will show a list of all known signatures. To query specific tuples, you have to use the signature syntax explained above. One command that might be used quite often is ls * to see all tuples.

You can also write to a tuplespace. To do so, just use the write command in combination with the signature syntax. The Java call ts.write(new Tuple("Stefan", true, 42.7, 'm') would be in a shell version write "Stefan"_true_42.7d_'m'. After the write command has been successfully processed, you'll also get the ID of the created tupel back.

To delete tuples, the commands rm or del are used in combination with a tuple signature. Please be aware that all deletion commands are internally mapped to deleteAll, i.e. all matches will be deleted. A deletion of all tuples that start with the string "action" would then be done by typing rm "action"_*.

It is also possible to monitor activities affecting a certain tuple signature by using the watch command. Technically this is very much comparable to a registration of the corresponding callback. So if you for instance want to know all notification tuples in the current space, just use watch "notification"_* and see what happens.

[top]

Administrative Commands

Additionally, there are also some commands that don't affect the tuples, but are more superuser functionalities. Right now there are three additional commands:

  • ps: Shows all connections to the server, including the username, the connection type, the remote address and some statistics.
  • health: Shows additionally some more information like some database connection infos, memory stats etc.
  • gm: Invokes the Garbage Manager, i.e. it deletes some obsolete tuple entries in the database. This is done automatically in a certain interval, but can also be triggered manually.
  • shutdown: Shuts the server down. Be sure you know what you do ...

[top]