=============================================================================== THINGS/THINGER 2009 Copyright Erich P Gatejen (c) 2001 through 2010 ALL RIGHTS RESERVED Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. For additional license information see the files in the directory doc/license =============================================================================== RELEASE VERSION 1.2 Things/Thinger is an experimental server and set of tools used to explore a various topics in computer science, some of which have long since moved on to their own open or proprietary projects. While the server is fully functional and has been used as a base for several other products, this release is primarily intended to be a toolkit for those doing their own projects or as a source code resource for ideas and solutions. Some of the code is great. Some of it is trash. It depends on my specific goal at the time. A few people have contributed to this code base, but most work by others has been in the encapsulating or follow-on projects. I will continue to do some maintenance, as it is needed for projects that it supported as of April 2009. I have no intention of supporting the general public, but it never hurts to ask. More information can be found in the doc/ directory. =============================================================================== PREREQUISITES - Release Version -- REQUIRED --------------------------------------------------------------- 1) JDK 1.6 or higher. It must be the JDK and not only the JRE. It uses the jdk/lib/tools.jar library. =============================================================================== INSTALLATION - Release Version 1. Run install.sh (for Linux) or install.bat with two arguments: the install directory for things (where you find this README.TXT) and the location of the jdk. If you run the script without arguments, it will give you help. And example run like this: ./install.sh /opt/things /usr/java/jdk1.6.0_03" That's it! You cannot run it again, so the install script will go away. =============================================================================== MANIFEST - Developers Version -- IN PACKAGE ------------------------------------------------------------- bin\ - Scripts bin\runsystemtest.bat - Script to run the system test bin\runsystemtest.sh - Script to run the system test bin\rununittest.bat - Script to run the system test bin\rununittest.sh - Script to run the system test bin\server-console.bat - Start the server with a console. bin\server-console.sh - Start the server with a console. doc\ - Documentation etc\ - Configurations etc\basic_config.prop - Simple, working config for the server. etc\config.layout - Install layout. install.bat - Install script. install.sh - Install script. lib\ - Runtime libraries. log\ - Runtime libraries. README.TXT - This file. universe\ - The storage UNIVERSE. VERSION - The version file. Note that the BASH or Windows .BAT files will disappear for the platform not installed. =============================================================================== USING IT -- THE CONSOLE ------------------------------------------------------------ When you start the server with the "server-console" script, the command line will accept commands after boot is complete. The command 'help' will display the help. Arguments are space delimited. The following is an example run: C:\dev\things\test\bin>server-console.bat Begin bootstrap. Starting multiprocessing kernel. The kernel process has started. Logging level set as DEBUG Loaded properties. System logger started. Data prepared. service HttpToolService started. service HttpCLIService started. service ConsoleService started. service CLIService started. service LocalCommandService started. Boostrap complete. help CLI Command system for THINGS. The following commands are available: ping (whisper) - Ping the server to see if it is alive. ps ('log') - Get the process list. Token 'log' will force the output to the log only (not the console). run [thing] - Run the thing named [thing]. setprop [name] [value] - Set a local property with the [name] and [value]. showprops - Show local properties. kill [pid] - Kill the process given by [pid]. help - Show this help. quit - Stop the server. Local properties will be applied to the THINGS run after they are set, and will disappear after the server is stopped. -- COMMAND INTERFACE -------------------------------------------- After the server is up, it listens on port 8801 for commands. It supports the same commands as console. You may use your web browser interact with the interface. If you go to http://localhost:8801/ you will get the help text. The following are examples: Go to: http://localhost:8801/ping wibble See: things.pingpong:OK:ETERNAL_HAPPINESS::pong=wibble: Go to: http://localhost:8801/ps See: things.processlist:OK:ETERNAL_HAPPINESS:>completed: >header=tag|id|clearance|runtime|name|state|state.numeric >entry=S3|kernel.service.3.consoleservice|PRIVILEGED|164486|ConsoleService|Running|400 >entry=S1|kernel.service.1.httptoolservice|PRIVILEGED|164486|HTTPToolService|Running|400 >entry=S4|kernel.service.4.cli|PRIVILEGED|164470|CLIService|Running|400 >entry=S5|kernel.service.5.localcommandservice|PRIVILEGED|164470|LocalCommandService|Running|400 >entry=K0|kernel|EXTREME|164548|kernel|Running|400 >entry=S2|kernel.service.2.httpcliservice|PRIVILEGED|164486|HttpService|Running|400 If you are using a regular web browser, you can use plain spaces between the command arguments (as shown in the 'wing wibble' example above). you can also use '%20'. So 'http://localhost:8801/ping wibble' would turn into 'http://localhost:8801/ping%20wibble' -- HTTP SERVER -------------------------------------------- The server implements a simple http server and an interface to write applications that use it. There are just a couple very simple pages included with this distribtion. The server listens on port 8802. Going to http://localhost:8802/ will give a simple page that looks like this: WELCOME TO THINGS Simple implementation nothing really here. Going to http://localhost:8802/PS will show the process list that looks like this: THINGS - PROCESS LIST header=tag|id|clearance|runtime|name|state|state.numeric >entry=S3|kernel.service.3.consoleservice|PRIVILEGED|211672|ConsoleService|Running|400 >entry=S1|kernel.service.1.httptoolservice|PRIVILEGED|211672|HTTPToolService|Running|400 >entry=S4|kernel.service.4.cli|PRIVILEGED|211656|CLIService|Running|400 >entry=S5|kernel.service.5.localcommandservice|PRIVILEGED|211656|LocalCommandService|Running|400 >entry=K0|kernel|EXTREME|211750|kernel|Running|400 >entry=S2|kernel.service.2.httpcliservice|PRIVILEGED|211672|HttpService|Running|400 =============================================================================== ADVANCED CONFIGURATION - The Command Interface (8001) and Http Server (8002) ports can be changed in the file etc/basic_config.prop. The server listens on no other ports.