ingenieurbüro für innovative informationstechnik

Dipl.-Ing. Jörg Beckmann

Start   »   Products   »   iiitAccessServer   »   Programming
  

Programming

Introduction

To connect clients to the iiitAccessServer, the server two has two interfaces. For applications written in Java a RMI interface exits, while other application may talk to the server using a TCP/IP socket.

Both interfaces are described in following sections.

The RMI Interface

Applications written in Java may talk to the iiitAccessServer using RMI. This method has the advantage, that there is a ready-to-use client library, which implements in addition to the pure communication a local cache. As a very simple example of a RMI client, you may look at SimpleClient. This program allows to send requests to the server and display the responses. Another example is the program ShutDown, which can be used to shut down a server running on the local host.

To create Java clients, the binary packages includes a client library named iiitAccessClient.jar. This jar file contains only those classes needed for the client.

The classes the RMI interface consists of are described in detail in the Guide for Java programmers.

The TCP/IP Interface

Applications not written in Java can use the TCP/IP interface to talk to the iiitAccessServer. With a simple protocol and an also simple command language commands can be sent to the server and responses can be received.

When opening the socket, the iiitAccessServer shall greet you with a message like:

iiitAccessServer - For help send command "HELP"
OK

The iiitAccessServer is now ready to receive commands.

The different commands will described below in separate chapters.

Every command will be answered with a result – if there is one – and a line with the content

OK

or with an error message

ERROR <number>: <message text>

All possible error messages are also described below.

After the response has been finished with OK or ERROR ..., the iiitAccessServer is ready again to receive the next command.

Commands of the TCP/IP server

The following commands are defined and will be discussed in the next chapters:

HELP
QUIT
SHUTDOWN
SETUSER=<user>
EXPR=<expression>

The server does not distinguish between upper- and lower case.

HELP

The command HELP is thought for interactive sessions. It gives you a short overview of the valid commands:

HELP - This help
QUIT - Close connection
SETUSER=<user> - Set user for expressions
EXPR=<expression> - Evaluate expression
OK

QUIT

This command closes the current session. It responses with a short notice:

Closing connection

This response does not end with OK, because the server will not accept any further command from this connection.

SHUTDOWN

The command SHUTDOWN takes a special role. It shuts down the iiitAccessServer. For security reasons, this command will only be accepted if send from localhost, e.g. with a telnet session like this one:

> telnet localhost 54321

The server responses with short notice like:

Closing connection and shutting down

This response does not end with OK also.

SETUSER

The command SETUSER=<user> sets the current user for ongoing requests of user rights. The name of the user must be sent as a parameter of the command:

setuser=joe
OK

EXPR

Last but not least the command EXPR=<expression> will be used to send the requests to the server. The parameter may be the name of a group, the name of a person, the name of an expression or even a dynamically created expression consisting of those components. Here are some examples:

setuser=joe
OK
expr=confirm
false
OK
expr=joe
true
OK
expr=confirm-joe
false
OK
expr=confirm+joe
true
OK

The server responses with true if the user is a member of the result set or false otherwise. The responses will finish with OK.

Error Messages

All error messages consist of the key-word ERROR, a unique error numer and a textual message. Currently, there are four different error messages defined, which will be discussed in the next chapters.

Unknown Command

This error message has the unique number 100. It will be sent if the command could not be recognized. Here are some examples:

help=1234
ERROR 100: Unknown command
asdf
ERROR 100: Unknown command
setuser
ERROR 100: Unknown command

ERROR 100: Unknown command

Syntax Error

This error message with the number 101 will be returned, if the command line contains syntactical errors. Here are some examples:

setuser=
ERROR 101: Syntax error
a+b
ERROR 101: Syntax error
a + b
ERROR 101: Syntax error
a s d f
ERROR 101: Syntax error

No user set

This error message will be sent if you requested a user right but did not set a current user. The error number is 200.

iiitAccessServer - For help send command "HELP"
OK
expr=confirm
ERROR 200: No user set

Expression can not be evaluated

If the expression could not be evaluated, you will get this error message with the error number 201. The cause of the error will be appended to the textual message. The following example shows the response if there is a syntactical error inside the expression, but there are other causes possible.

expr=confirm*joe
ERROR 201: Expression <confirm*joe> can not be evaluated
- There is something strange near position 7 in <confirm*joe>

(In reality, this message will be printed in one line)

Invalid user ID

The error message will be printed if the global configuration attribute VerifyUser is true and an invalid user ID is passed to the command SETUSER.

iiitAccessServer - For help send command "HELP"
OK
setuser=joe
OK
setuser=bob
ERROR 202: Invalid user ID

Expressions

Picture 1

The possibilities of the iiitAccessServer are described in detail in our White Paper. Therefore we will give you an overview of the syntax of expressions only.

As shown in the picture, two groups can be combined. Mathematically spoken, the set C is a union of sets

C = A B.

Because set operations can not be expressed with the common ASCII character set, it will be written as

C = A + B

inside iiitAccessServer.

The second example shows the intersection of the sets C and D with the exclusion of set E. The mathematically correct representation of this operation

F = C D \ E = (A B) D \ E

can also not be written with the ASCII characters. Therefore it will be written as

F = C & D - E = (A + B) & D - E.

inside iiitAccessServer. The result will include all users which are members of groups C and D but not members of group E.

All these formulas can be written as Strings this way:

(x + y + z)
A set consisting of the elements x, y, and z.
(A + B)
The union of the sets A and B. The result will include all elements of the sets A and B.
(A - B)
The difference of the sets A and B. The result includes all elements of A, which are not included in B.
(A & B)
The intersection of the sets A and B. The result will include all elements which are included in A and included in B.
((x + y + z) + A) - (b + e + f) & C
Expression can be grouped with braces. They are resolved from left to right. "&" has a higher priority than "+" and "-".

Guide for Java programmers

Until now, there is no Java programmer's guide but the JavaDoc API Documentation.
Top