Home

Reference Manual

image

Contents

1. void load Loads the buddy list into the client remove void remove String username Removes a buddy from the list removeAll void removeAll Removes all buddies from the list Buddies 45 a s gt ar removeListener void removeListener Object listener Removes the specified listener from this object onError onError Error error Event handler invoked when an error occured that was caused by one of the methods of the Buddies object oninsert onInsert String username Event handler invoked when a buddy was inserted onLoad onLoad Array String usernames Event handler invoked when the buddy list was loaded onRemove onRemove String username Event handler invoked when a buddy was removed onRemoveAll onRemoveAll Event handler invoked when all buddies were removed Class The class object contains methods to register your custom ActionScript classes so that objects of that class can be exchanged between clients After you registered one of your custom classes you can use objects of that class as a value of a user or group property or as part of an attachment of a Mail or M essage object It ensures that your objects will be unmarshalled in other clients with all their properties and methods Please note that only methods that you added to the prototype object of the constructor can be attached to the unmarshalled object Th
2. this users propSet getOwner av 18 Example Application show graphics for the new room _root main gotoAndStop org omus group getName reload the group list to refresh the numbers on the map org omus info loadGroupList It removes all the avatars of the old group and creates a new avatar object for each PropertySet object in the array returned by the getAllUserProperties method of the group object each user of the group is represented through her corresponding PropertySet object The movie clips to display the avatars will be attached in the con structor for the avatar object see the section on avatar as for details If a new user enters the room i e a user controlled by a different client the onUserJoined event handler will be called RoomObj prototype onUserJoined function propSet var av new _root Avatar0bj propSet this depth this users propSet getOwner av org omus info loadGroupList It creates a new avatar object the same way the onChange event handler does The onUserLeft event handler removes the corresponding avatar from the screen The onClick handler is called when a user clicks on the map in the upper right corner or when she clicks on the main stage In the latter case the position property of the user is changed and synchronized so that all other clients get notified If the main stage was clicked a random start position for the new room is calculated and then the c
3. Sorts all M ail objects by sender sortBySubject void sortBySubject boolean ascending Sorts all M ail objects by subject onError onError Error error Event handler invoked when an error occured that was caused by one of the following methods of the M ailbox object load removeAll onLoad onLoad Mailbox box Event handler invoked when all M ail objects have been loaded into the M ailbox object onNewMail onNewMail Mailbox box Event handler invoked when a new mail was received by the server The corresponding M ail object will not be loaded automatically thus getLoaded and getTotal will return different numbers after this event handler was invoked You can use the load method at any time to load all new M ail objects into the client onRemoveAll onRemoveAll Mailbox box Event handler invoked when all M ail objects have been removed from the M ailbox object Mailbox 69 a E 5 gt a Message The M essage object has only a small subset of the methods of the M ail object M essage objects are different from M ail objects in that they are not persistent They can be sent using one of the methods of org omus messenger The attachment is a normal ActionScript object and can carry any of the following datatypes boolean number String Date Object Array org omus Table You can write code to construct and send a message as follows var msg new org omus Message chat
4. lt startup server s1 name entranceHall gt lt group gt N ow three groups named kitchen bathroom and entranceH all will be created when the server boots All three groups will load and use the Java class M yExtension Furthermore all new groups created dynamically due to a client calling the change method of the Group object in the client API and specifying groundFloor as the configlD will use that class too 4 Reboot Oregano Server Writing server side extensions 95 PEELEN Package Overview org omus ext Contains five interfaces that you can use to develop extensions for the O regano Server Each extension must implement one of these five interfaces and the corresponding class name must be specified in config xml so that the server can load the extension GroupExtension is the main interface of that package that can be used to extend the functionality of one or more groups org omus core Contains the core classes Group User and PropertySet are classes that are very simi lar to their client side twins of the same name Use these objects to read and modify properties and to send messages to clients Furthermore this package contains a lot of additional utility classes org omus data Contains the wrapper classes for the datatypes that can be exchanged with Flash Clients Each property and each M essage object contains data wrapped in one of the subclasses of the abstract superclass DataField Th
5. removeListener void removeListener Object listener Removes the specified listener from this object onError onError Error error Event handler invoked when an error occured that was caused by one of the methods of the info object onFindUser onFindUser String username String groupName Event handler invoked when a user was located groupN ame may be nul1 if the user is currently offline or does not exist onLoadGroupList onLoadGroupList Table groups Event handler invoked when the group list was loaded either due to a call to loadGroupList or due to a regular update sent by the server Each row in the table con tains information about a single group currently active on the server The columns are name String userCount number userLimit number and closed boolean onLoadUserList onLoadUserList Array String usernames Event handler invoked when the user list was loaded either due to a call to loadUserList or due to a regular update sent by the server Locks The Locks object can be used to restrict access to certain items within a group The locks are valid within one group only if a user leaves a group all locks that he previ ously aqcuired will bereleased automatically You obtain a reference to the Locks object with org omus user getLocks The names of the locks are arbitrary strings An example is a whiteboard application with some draggable objects on the screen To pre
6. BooleanField BooleanField String name boolean value Creates a new BooleanField with the specified name and value getBoolean boolean getBoolean Returns the value of this BooleanField object as a boolean primitive setBoolean void setBoolean boolean newValue Sets the value of this BooleanField to the specified boolean primitive CounterField extends DataField implements Cloneable Serializable A special class for synchronizing int values This is the only subclass of DataField that is not just a Java class corresponding to an ActionScript datatype It makes it possible to modify int values relative to their current value and thus avoid any synchronization issues that might occur if different clients modify the int value of a group property con currently An example Let s assume you created a Flash client that shows a basket and each user in the group can put any amount of apples into the basket and take any amount out of it If two users put an apple into that basket concurrrently and both clients add 1 to the current number of apples and then send the new total value to the server only one of the two apples gets added to the group property on the server side If a property is con figured to be a counter the setValue method of the client side PropertySet object changes the value relative to the current value This way the server receives two add 1 apple commands and thus both apples are added to the b
7. Properties of the current user org omus user getProperties Properties of another user in the current group org omus group getUserProperties username Properties of other groups or users who are not members of the current group are not loaded into the client automatically Use the PropertyLoader object to read the values of these properties N ote that modified values will not be written to the database and not be reflected in other clients before you commit all changes with a call to PropertySet synchronize Example code to change three properties of a user named Billy and synchronize them might look as follows var propSet org omus group getUserProperties Billy propSet setValue age 27 propSet setValue married false propSet setValue children Jenny Carmel Larry propSet synchronize Method Summary void addListener Object listener boolean contains String propName String Group getOwner ProperySet getParent int getPrimaryKey String getType String propName any getValue String propName boolean isLoaded String propName boolean isModified String propName boolean isSynchronized boolean isValid void load Array String propNames void loadAll void removeListener Object listener void setValue String propName any newValue int size void synchronize PropertySet 71 a E 5 gt a Event Summary onError PropertySet subset Error error o
8. PropertySet ps group getProperties StringField st StringField ps getValue foo st setString result 104 Group group addCommand com2 Services getTaskManager executeNow com1 With this approach you avoid to slow down the group queue with your time consum ing calculation but are still able to pass ts result to one of the protected methods close void close Closes the group so that no other users can join getAllUsers Iterator getAllUsers Returns an Iterator over all the User instances of this group getConfiglD String getConfigID Returns the configlD of the group It identifies the corresponding lt group gt node in con fig xml that was used to configure this group You can create an unlimited number of groups with the same configlD but different names See the Configuration chapter for more details getName String getName Returns the name of the group getProperties PropertySet getProperties Returns the PropertySet object associated with this group o El ga o 3 S Nn a O 2 5 getUser User getUser String name Returns the User object identified by the specified user name Group 105 getUserCount int getUserCount Returns the number of users who are currently member of this group getUserLimit int getUserLimit Returns the maximum number of users permitted for this group isClosed boole
9. The org omus namespace 43 n s gt 2 clients After the user has logged in four more objects are created in the org omus namespace org omus group org omus user org omus messenger org omus info All the other objects must be either created by hand or must be obtained through a method of another object If you create a client side O regano object that has a public constructor you must also use the namespace for the constructor as follows var pl new org omus PropertyLoader Reference The reference contains only the public methods of each object If you look into the ActionScript include files you will find many methods and classes that are not men tioned in the reference Using one of those methods in your application might lead to unexpected results Unfortunately ActionScript methods do not have access modifiers like Java methods so it was impossible to declare them as private But as long as you use only the documented methods you are on the safe side Each section in the reference describes one object It first gives you an overview of all the methods and event handlers available in that object and then describes each method in detail The notation of each method entry looks as follows getUserProperties PropertySet getUserProperties String username This may seem a bit unfamiliar for ActionScript programmers It includes the datatype of the return value and the datatypes of all arguments Of course
10. ing messages that have the subject chat message It adds the incoming messages to the chat array and updates the field on the stage ChatObj prototype onMessage function msg if msg getSubject chat message if this txt length gt 5 this txt shift var attach msg getAttachment this txt push msg getSender attach txt Varustir m for var i O i lt this txt length i str this txt i n gt 5 ack gy Ea o E a dwex3 _root chatClip chatText str W hen the user hits the return key the sendMsg method is called ChatObj prototype sendMsg function if Key getCode Key ENTER var txt _root chatClip input var msg new org omus Message chat message msg getAttachment txt txt org omus messenger sendToGroup msg _root chatClip input The chat object uses M essage objects to exchange data whereas the room object uses properties to exchange the avatar position coordinates between clients See the Exchanging Data section in the Client API chapter for a thorough discussion on when to use which approach Example Application 21 CHAPTER 4 Configuration config xml the main configuration file The main configuration file is included in the config directory of your O regano server run time directory This chapter describes each attribute of each node in the file optional attributes are marked with an If you build a
11. lt serverConfig gt Contains no attributes and one or more server child nodes Each machine in use must be configured with a corresponding server node In most cases O regano Server will run on one machine but you can easily build scalable server clusters See the Installation chapter for more details Example lt serverConfig gt lt server id serv1 address www1 myserver com userLimit 200 dynamicGroups true gt lt serverConfig gt 25 N 3 oq E y o lt server id serv2 address www2 myserver com userLimit 200 dynamicGroups true gt lt serverConfig gt lt server gt Contains four required attributes and no child nodes Example lt server id serv1 address www myserver com userLimit 200 dynamicGroups true gt id The id of the server An arbitrary string that can be used in the groupConfig node where you must specify the server for each group that you want to be created during startup address The address of the server M ust match the name that you specified in the start script See the Installation chapter for more details userLimit The maximum number of connections permitted for this server If Oregano Server runs on more than one machine each can have its own user limit dynamicGroups Boolean value If this attribute is set to true this machine will be included in the built in server load balancing that always chooses the server with the
12. A logging facility and an object that gets passed to each onError event handler Event Model With Flash M X anew event model was introduced If you are already familiar with that new model you will quickly get used to the way the objects in the O regano Client work M ost of those objects generate events usually when they receive data or an error mes sage from the server To get notified of the event a listener has to be registered with that object The listener must contain methods for one or more of the events it is interested in It can simply be a generic ActionScript object with an event handler method attached to it or it can be one of your own custom classes The M essenger object for example generates an onMessage event each time it receives a message sent from the server To handle incoming messages you can write code like this var lis new Object lis onMessage function msg trace received a message trace the subject is msg getSubject org omus messenger addListener lis N ow each time a message is received in the client two lines will be added to the output window You will find more examples of listeners in the Reference section of this chap ter In addition to the regular events almost every object generates onError events passing an org omus Error object as an argument You can use the methods of that error object to obtain the error code an description of the error or the name of the me
13. DataField df Inserts the specified DataField at the specified position in this list addAll void addAll DataList list Appends all the DataFields of the specified DataList to the end of this list The order of the elements of the sprecified DataList will be preserved 126 DataList addAll void addAll int index DataList list Inserts all the DataFields of the specified DataList at the specified position in this list The order of the elements of the sprecified DataList will be preserved clone Object clone Returns a deep copy of this DataList get DataField get int index Returns the element at the specified position in this list iterator Iterator iterator Returns an iterator over the elements in this list remove DataField remove int index Removes and returns the DataField at the specified index position removeAll void removeAll Removes all elements from this list size int size Returns the number of DataFields of this D ataList sort void sort DataList Comparator listComp Sorts the list according to the order induced by the specified comparator DataList 127 ejep snwo si0 DataList Comparator Inerface DataList Comparators can be passed to the sort method of DataList to allow precise control over the sort order Method Summary int compare DataField fi DataField f2 compare int compare DataField f
14. The sender represents the client that modified the properties PropertyU pdate is a subclass of PropertySet This object does not contain all the properties that are associated with this group but only the modified ones You can implement some kind of error checking and only return true if you want the new values to be accepted and synchronized If you return false to reset all affected properties to their old value you can use the setErrorCode method of the PropertyU pdate object to send customized error codes to the client who attempted to change the value Otherwise a default error code will be sent syncUserProperties boolean syncUserProperties PropertyUpdate newValues User sender User owner Invoked before the properties of the specified owner will be synchronized The sender represents the client that modified the properties PropertyUpdate is a subclass of PropertySet This object does not contain all the properties that are associated with the owner but only the modified ones You can implement some kind of error checking and only return true if you want the new values to be accepted and synchronized If you return false to reset all affected properties to their old value you can use the setErrorCode method of the PropertyU pdate object to send customized error codes to the client who attempted to change the value O therwise a default error code will be sent userJoined void userJoined User user DataRow extraData Invo
15. void load String propNames void loadAll int size void synchronize contains boolean contains String name Returns true if this PropertySet object contains a property with the specified name getOwner Object getOwner Returns the owner of this PropertySet object The returned object is either an instance of Group or an instance of User getPrimaryKey IntField getPrimaryKey Returns the primary key for this PropertySet object corresponding to the usrID and grpID fields in the userprops and groupprops tables in the database getType Class getType String name Returns the type of the property with the specified name getValue DataField getValue String name Returns the value of the property with the specified name or null if the property was not loaded yet To modify the value use one of the methods of the returned DataField 114 PropertySet isLoaded boolean isLoaded String name Returns true if the value of the property with the specified name has been loaded from the database isModified boolean isModified String name Returns true if the property with the specified name was modified since the last syn chronization load void load String propNames Loads all values of the properties with the specified names into the client N ote that the values of all properties except for those with a cacheLevel attribute set to off will be loaded into the
16. User The values between 2 and 8 make no difference to the Oregano Server You can use them for your application logic A user who has administrator status will not be logged out if you switch the server to debug mode using the admin client getProperties PropertySet getProperties Returns the PropertySet object associated with this user logout void logout String errorCode Logs out the user passing the specified error code to the client before closing the con nection sendToClient void sendToClient Message msg Sends the specified M essage to the Flash client of this user The message will be received in the onMessage event handler in the client side M essenger object 310 SNUWO B10 User 121 Package org omus data Contains classes that represent ActionScript datatypes that can be passed to the server and written to the database All the conversion steps are done automatically ActionScript datatypes will be marshalled sent to the server converted to their corre sponding J ava types and if they are part of a persistent property or mail attachment written to a field in the database with a matching SQL type according to the following conversion table ActionScript datatype Java datatype SOL type boolean Boolean Field TINYINT number CounterField INTEGER number IntField INTEGER number LongField BIGINT number DoubleField DOUBLE Date DateField TIMESTAMP String StringField VARCHAR LONGV
17. a user removeListener void removeListener Object listener Removes the specified listener from this object onError onError Error error Event handler invoked when an error occured that was caused by one of the methods of the PropertyLoader object onLoadGroup onLoadGroup String groupName Object props Event handler invoked when properties of a group were loaded The properties are included in a plain ActionScript object not in a PropertySet object because they can not be modified or synchronized like those of the current group 76 PropertyLoader onLoadUser onLoadUser String username Object props Event handler invoked when properties of a user were loaded The properties are included in a plain ActionScript object not in a PropertySet object because they can not be modified or synchronized like those of users in the current group PropertySet Each group and each user have a set of properties associated with them The datatype as well as persistence and synchronization settings for each property must be defined in the XM L configuration file on the server See the Configuration chapter for details The PropertySet object can be used to read or modify the values of individual properties to load properties into the client or to synchronize them You can obtain references to PropertySet objects with one of the following methods Properties of the current group org omus group getProperties
18. admin client to logout users or shutdown the server 24 lt admin gt versionID An arbitrary string The versionID must be entered on the login screen in the Flash admin client If the versionID of a client does not match the value of this attribute login will be prevented This attribute is optional It must be specified if enableClient is set to true keyGenerator The name of the class to be used to generate keys for password encoding This attribute is optional The specified class must implement org omus ext KeyGenerator and must always be used in conjunction with a password decoder See the section on KeyGenerator in the Server API chapter passwordDecoder The name of the class to be used to decode passwords This attribute is optional The specified class must implement org omus ext PasswordDecoder and must always be used in conjunction with a key generator See the section on PasswordD ecoder in the Server API chapter N ote that you must implement the corresponding encoder function in the client Create a new empty Flash file and on the first frame define a function called encode function encode password serverKey var str encode the password using the serverKey return str Export that movie with the name encode swf and move that file to the directory of your Oregano Admin Client Before you login with the Admin Client make sure to check use external password encoder on the first screen
19. all properties of the other users in the group to the client Well there are exceptions depending on the configuration of the properties but let s keep this example simple Properties handle all the persistence and synchronization stuff for you The only extra work that you have to do is to define each property you want to use in config xml Let s add some code To send the chat message to other clients you write code like this sendChatMsg function chatMsg var msg new org omus Message chat message var attach msg getAttachment attach chatText chatMsg org omus messenger sendToGroup msg The other clients receive this message in the onMessage event handler of the M essenger object You must add a listener to handle the message var lis new Object lis onMessage function msg if msg getSubject chat message var chatMsg msg getAttachment chatText var sender msg getSender display chatMsg org omus messenger addListener lis 42 Exchanging data When an avatar changed its position you must modify the value of the corresponding property changePosition function username xpos ypos var propSet org omus group getUserProperties username propSet setValue position x xpos y ypos propSet synchronize J For the other clients to be notified they must have a listener for onSynchronize events registered with the PropertySet object var lis new Obje
20. and the same DataFields as the speci fied DataR ow clone Object clone Returns a deep copy of this DataRow contains boolean contains String name Returns true if this DataRow contains a DataField with the specified name get DataField get String name Returns the DataField with the specified name or null if no such DataField exists getASClass String getASClass Returns the registered name of an ActionScript class or null if none has been set iterator Iterator iterator Returns an iterator over the DataFields in this DataR ow put void put DataField df Adds the specified DataField to this DataRow ejep snwo si0 DataRow 129 putAll void putAll DataRow dr Adds all DataFields of the specified DataR ow to this DataR ow remove DataField remove String name Removes and returns the DataField with the specified name Returns null if no such DataField exists removeAll void removeAll Removes all DataFields from this DataR ow setASClass void setASClass String className Sets the name of the ActionScript class for this DataRow to the specified string The objects can only be sent to the client and converted to the corresponding custom ActionScript objects if a constructor with a corresponding name was registered with the client See the section about the Class object in the Client API size int size Returns the number of
21. can create an unlimited number of groups and extend their built in functionality with server extensions written in Java Built in features include messaging or synchronization of the properties of all members of a group Simple multiuser applications like chat sys tems can be written with a few lines of ActionScript and without the need to develop server side extensions Real time Messaging and Serialization Easily exchange data between clients or push data from the server to the client Or use persistent messages so that a user who is currently offline receives the message the next time she logs in The content of messages is not restricted to strings you can exchange many different ActionScript datatypes and objects including Date Array or the gener ic Object which will be serialized and converted to their corresponding J ava datatypes automatically No more cumbersome and error prone parsing of strings Synchronization Properties associated with a user or a group can be modified and synchronized easily with client side or server side methods Synchronization and persistence settings can be configured separately for each property associated with a group or a user A property can be configured to be synchronized with every client to be loaded into the server side cache only or to be read from the database each time it is accessed Furthermore it can be configured to be persistent or transient All the typical requirements for synchro ni
22. cluster you only have to edit the configuration file on the Primary Server all the other servers will load the file from that location lt login gt Contains three required attributes and no child nodes Example lt login mode public versionID tr 4s emailUnique true gt mode This attribute accepts one of the following two values public every registered user who is not banned is permitted to login debug only administrators users with a permission value set to 9 or 10 are permit ted to login versionID An arbitrary string The versionID must be passed to the init method of the client side Session object If the version D of a client does not match the value of this attribute login will be prevented This way you can make sure that only clients with the current version of your application can log in emailUnique Boolean value If set to true the server prevents that two users with the same email address are registered with the server 22 lt login gt lt ports gt Contains one required attribute three optional attributes and no child nodes Example lt ports login 1442 reconnect 1443 admin 1705 rmi 1099 gt login The login port A number between 1024 and 65535 This port number must be passed to the init method of the client side Session object reconnect The reconnect port A number between 1024 and 65535 This attribute is optional It must be specified if the O regano Ser
23. executeDaily Command com Executes the specified Command every day at the time specified in the lt statistics gt node in config xml executeMonthly void executeMonthly Command com int dayInMonth Executes the specified Command each month on the specified day at the time specified in the lt statistics gt node in config xml Valid values for daylnM onth range from 1 to 31 obviously 118 TaskManager executeNow void executeNow Command com Delegates the execution of the specified Command to one of the worker threads in the Oregano Thread pool executeWeekly void executeWeekly Command com int dayInWeek Executes the specified Command once a week on the specified day at the time specified in the lt statistics gt node in config xml Valid values for daylnWeek range from 1 Sunday to 7 Saturday schedule void schedule TimerTask task Date time Schedules the specified task for execution at the specified time schedule void schedule TimerTask task Date firstTime long period Schedules the specified task for repeated fixed delay execution beginning at the speci fied time For details see the documentation for the corresponding method in java util Timer schedule void schedule TimerTask task long delay Schedules the specified task for execution after the specified delay schedule void schedule TimerTask task long delay long period Schedules the specified
24. extensive Client API enables you to develop a complex multiuser application with out a single line of server side code But sometimes you need to move parts of your application logic to the server especially if you add features that need to be synchro nized within a group Oregano Server comes with a set of interfaces that can be used to develop extensions in Java The most important interface is GroupExtension which can be used to extend the functionality of a group There are four steps required to add an extension to the server 1 Write a class that implements one of the five interfaces in package org omus ext omus is the acronym for Oregano M ultiuser Server 2 Compile the class and move the class file into the extensions directory inside the server runtime directory of Oregano Server 3 Include the name of that class in config xml There are many places in this file where you can specify an extension class It depends on the type of extension you wrote and on the way it is going to be used See the Configuration chapter for details If you wrote a class that implements GroupExtension you can specify it to be the default extension for all groups or to be used within a particular subset of groups only In the latter case the entry in config xml might look as follows lt group configID groundFloor userLimit 50 extension MyExtension gt lt startup server s1 name kitchen gt lt startup server s1 name bathroom gt
25. group This event may originate from a client calling sendToGroup in org omus mes senger or from any server extension calling sendToGroup in the M essagingM anager Return true if you want the message to proceed on its way to the clients messageToUser boolean messageToUser Message msg User recipient Invoked before a message is sent to the specified user This event may originate from a client calling sendToUser or sendToA11 in org omus messenger or from any server extension calling sendToGroup Or sendToA11 in the M essagingM anager Return true if you want the message to proceed on its way to the client prepareGroupCreation boolean prepareGroupCreation GroupCreationData gcd Invoked before the group will be created The GroupCreationData object contains methods to read the name and the configlD of the group that is supposed to be creat ed If this method returns false the creation of this group will be aborted This way you can implement some kind of error checking on the server or load some additional data before the group is created You can use the setErrorCode method of the GroupCreationData object to send customized error codes to the clients in case you want to prevent the creation of that group Otherwise a default error code will be sent 98 GroupExtension syncGroupProperties boolean syncGroupProperties PropertyUpdate newValues User sender Invoked before the properties of this group will be synchronized
26. highest difference between the user limit and the number of currently connected users to dynamically cre ate a new group If this attribute is set to false no groups other than those that were created during startup can be created on this server 26 lt server gt lt database gt Contains six required attributes and one child node Example lt database url jdbc mysql localhost oregano_db driver org gjt mm mysql Driver userID herbert password flyn4 re connectionLimit 25 transactions false gt lt typeMap gt lt see typeMap section gt lt typeMap gt gt url The URL of the database The format of the URL is specific to the JDBC implementa tion of your database For M ySQL it looks like this a o 3 oa y o jdbc mysql localhost omus10 This URL says to use the mysql driver to connect to the database omus10 On localhost You should find the URL format for your driver in the documentation that comes with it driver The fully classified class name of your driver e g org gjt mm mysql Driver M ake sure that the Driver is included in the jre lib ext directory of your JRE installation userlD The user ID that should be used to connect to the database password The password that should be used to connect to the database connectionLimit The maximum number of concurrent connections to the database transactions Boolean value Should be set to true unless y
27. of a secondary server because these machines must register with the primary server during startup On a Primary or Standalone server leave this entry empty RMI_PORT A port number between 1024 and 65535 corresponding to the rmi attribute of the ports node in config xml This value is only required in the start script of a secondary server because these machines must register with the primary server during startup On a Primary or Standalone server leave this entry empty MEMORY_INIT The initial heap size Default is 64M MEMORY_MAX The maximum heap size Default is 128M 14 Installation Booting Oregano Server Open a shell window Change into the Oregano Server runtime directory Run start sh on Linux or start bat on Windows On Linux the output is redirected to nohup out so you have to peek into that file to know if the server has booted suc cessfully the best way is to execute tail f nohup out When you see the line server running Oregano Server has finished booting and is accepting connections You can now try the example application that you can download from www oregano server org See Chapter 3 for a description of that application When the output includes the line Ej n ee EA ny o 5 server boot aborted See bootLog txt for details open that file in the log directory to see what went wrong Installation 15 CHAPTER 3 Example Application If you skip through this manual you might
28. onLogout onLogout Error error Event handler invoked when the user has been logged out You can use the specified error object to find out about the cause of the logout See the section on error codes at the end of this chapter for a list of possible codes onRegister onRegister Object data Event handler invoked when an attempt to register a user succeeded The argument is an empty object unless you wrote a LoginExtension as a server side plugin which can be used to send additional data to the client Table Table objects are the only datatype used for user and group properties that are not built in ActionScript objects The rows of the table are plain ActionScript objects with their property names match ing the column names of the table N ote that the event handlers of the table object will only be invoked if the table is a value of a synchronized property If the property is not synchronized or the table is Table 83 a 5 gt a nested in another structured value in a property or you created a new table object by hand the event handlers will not be invoked Table objects are especially useful if you have large amounts of data in a user or group property since the table object will only be partially synchronized Only the modified added or removed rows will be exchanged between clients so you can save a lot of bandwith Properties of type Array or Object on the other hand will always be full
29. properties of users who are offline Example code to load two properties of a user might look as follows var pl new omus PropertyLoader var lis new Object lis onLoadUser function username props trace properties of user username trace age props age trace married props married were loaded lis onError function error var name error getArguments 0 trace properties of user name could not be loaded trace error error getDescription pl addListener lis pl loadUser Jenny age married Constructor Summary new org omus PropertyLoader Method Summary void addListener Object listener void loadGroup String groupName Array String propNames void loadUser String username Array String propNames void removeListener Object listener PropertyLoader 75 a E 5 gt a Event Summary onError Error error onLoadGroup String groupName Object props onLoadUser String username Object props new new org omus PropertyLoader Creates a new PropertyLoader addListener void addListener Object listener Adds the specified object as a listener for all the events the PropertyLoader object can generate loadGroup void loadGroup String groupName Array String propNames Loads properties of a group loadUser void loadUser String username Array String propNames Loads properties of
30. server side PropertySet object automatically See the Configuration chapter for more details loadAll void loadAll Loads the values of all properties that are not loaded automatically size int size Returns the number of properties in this set synchronize void synchronize Synchronizes all modified properties in this set according to the synchronization settings in the XML configuration file on the server This may include writing the new values to the database or updating them in one or all clients of the current group depending on the configuration PropertySet 115 o El ga o 3 S Nn a o 2 5 PropertyUpdate extends PropertySet implements Serializable A subset of a PropertySet instance that gets passed to the syncUserProperties and syncGroupProperties methods in org omus ext GroupExtension It contains only the properties that were modified It inherits all the methods of PropertySet and adds three additional methods to read and set an additional error code or to obtain a refer ence to the parent ProprtySet Method Summary String getErrorCode ProperySet getParent void setErrorCode String err getErrorCode String getErrorCode Returns the error code of this instance or null if none was specified yet getParent ProperySet getParent Returns the parent object of this PropertyUpdate The PropertyU pdate instances that get passed to the syncUserProperties
31. setDate Date newValue DateField DateField String name Date value Creates a new DateField with the specified name and value getDate Date getDate Returns the value of this DateField setDate void setDate Date newValue Sets the value of this DateField to the specified Date DoubleField extends DataField implements Cloneable Serializable ejep snwo si0 The class corresponding to the number datatype in ActionScript DoubleField 133 Constructor Summary DoubleField String name double value Method Summary double getDouble void setDouble double newValue DoubleField DoubleField String name double value Creates a new DoubleField with the specified name and value getDouble double getDouble Returns the value of this DoubleField as a double setDouble void setDouble double newValue Sets the value of this DoubleField to the specified double FieldListener Interface A listener that gets notified when the value of a DataField changes Can be registered with any DataField through its addListener method Method Summary void fieldChange DataField field fieldChange void fieldChange DataField field Invoked when the value of the specified D ataField was modified 134 FieldListener FieldVisitor Interface A visitor that can be used to extend the functionality of all DataFields without modify ing their API Can be passed
32. single group or all the groups in the server and you can write custom code to be executed before a user is logged in so you are able to authen ticate her with legacy systems The extensions are plain J ava classes that implement one of the five interfaces that serve as a hook into the server Documentation Oregano Server comes with a 150 page user manual It contains a description of each method of the Client API and Server API and each attribute of each node of the XML configuration files as well as example code for a simple chat application that you can use as a Starting point for your own application 10 Feature Overview CHAPTER 2 Installation Ej n ee EA a o 5 Installing the Java Runtime Environment To run Oregano Server you need the JRE 1 4 0 or later If you are not sure which ver sion is installed on your machine open a shell window and execute the command java version You can download the latest JRE from java sun com Simply follow the installation instructions on the download page After you are done installing the JRE you must add the bin directory inside the installation directory to the PATH environment variable The procedure differs for each platform Linux bash Add a line such as the following to the end of your bashrc export PATH path to jre bin PATH Linux C shell Add a line such as the following to the end of your cshrc set path path to jre bin path Windows XP 20
33. test your Flash movies inside a browser you can use this event handler to send the logging information to a popup win dow or display it in your Flash movie Mail Each M ail object represents a single mail It has a subject a sender and a recipient like normal internet email has too But it does not have a body so all the text that you want to transmit with your mail has to be put into the attachment But the attachment is not restricted to string objects It is a normal ActionScript object and can contain any of the following datatypes boolean number string Date Object Array org omus Table You can write code to construct and send a mail as follows var mail new org omus Mail personal information var attach mail getAttachment attach name Brian attach age 37 attach married false attach children Jenny Maria Ben var listener new Object listener onSend function mail trace mail has been sent listener onError function mail error trace sending mail failed error getDescription mail addListener listener mail send Jennifer Constructor Summary new org omus Mail String subject Method Summary void addListener Object listener Object getAttachment Mail 63 n E 5 gt a Date getDate Mailbox getMailbox String getRecipient String getSender String getSubject boolean isLoaded boolean isUnread voi
34. void debug String errorCode Exception e String info Creates a log entry with the specified error code info string and the stackTrace of the specified Exception if the LogM anager is configured to process messages of level DEBUG or higher The error code will be automatically prefixed with ext to avoid confusion with built in error codes debugEnabled boolean debugEnabled Returns true if the LogM anager is configured to process log entries of level DEBUG or higher error void error String errorCode Creates a log entry with the specified error code if the LogM anager is configured to process messages of level ERROR The error code will be automatically prefixed with ext to avoid confusion with built in error codes error void error String errorCode String info Creates a log entry with the specified error code and info string if the LogM anager is configured to process messages of level ERROR The error code will be automatically pre fixed with ext to avoid confusion with built in error codes error void error String errorCode Exception e Creates a log entry with the specified error code and the stackTrace of the specified Exception if the LogM anager is configured to process messages of level ERROR The error code will be automatically prefixed with ext to avoid confusion with built in error codes error void error String errorCode Exception e String info Creates a log e
35. 00 NT 4 Start the control panel select System then Environment Add the bin directory to the User Variable named PATH using a semicolon to separate the new entry like this c path to jre bin other stuff Windows 98 ME Add a line such as the following to the end of your AUTOEXEC BAT SET PATH c path to jre bin PATH To test whether you did it right execute the command java version again Installation 1 Installing the JDBC driver Assuming that your database engine is installed and running you need to install a DBC driver for that database For M ySQL you can download the driver from www mysql com M ove the driver to the jre 1ib ext directory inside your JRE installation directory If booting Oregano Server fails with a message like this error initializing connection pool server boot aborted see bootlog txt for details and bootlog txt contains lines like this creating ConnectionPool error initializing connection pool java lang ClassNotFoundException org gjt mm mysql Driver at java net URLClassLoader 1 run URLClassLoader java 200 then the JDBC driver is not properly installed Another common cause for errors is that M ySQ L is configured with the skip networking option If you cannot connect to M ySQL with Oregano although the driver is loaded correctly check that this option is commented out in my cfg Installing Oregano Server Two archives in the download section at www oregano server org are mandatory f
36. 1 DataField f2 Compares its two arguments for order Returns a negative integer zero or a positive integer as the first argument is less than equal to or greater than the second DataRow extends DataField implements Cloneable Serializable The class corresponding to the generic Object in ActionScript When an object is sent to the server it will be converted to a DataRow instance and each property of the ActionScript object is converted to the corresponding DataField and put into the DataRow instance DataRow is similar to java util Map but the keys are limited to Strings and the values are limited to DataFields If you want to map a server side DataRow to a custom client side ActionScript class you can use the setASClass method in DataR ow In addition this class must be registered with the same name with the register method in the client side org omus Class object Constructor Summary DataRow String name DataRow String name DataRow dr Method Summary Object clone boolean contains String name DataField get String name String getASClass Iterator iterator void put DataField df void putAll DataRow dr DataField remove String name void removeAll void setASClass String className int size 128 DataRow DataRow DataRow String name Creates a new DataRow with the specified name DataRow DataRow String name DataRow dr Creates a new DataRow with the specified name
37. ARCHAR Array DataList VARCHAR LONGVARCHAR Object DataRow VARCHAR LONGVARCHAR org omus Table DataTable VARCHAR LONGVARCHAR All classes in the Java column are subclasses of DataField At first glance you might think that working with those Oregano Wrapper types like IntField is cumbersome compared to working with Java primitive datatypes or classes like ArrayList or HashM ap But the DataField family is efficient for two reasons First they keep track of all changes Each DataField type generates fieldChange events and you can register listener objects to handle this event In the case of complex datatypes like DataList the event bubbles up in the container hierarchy until it reaches the outermost container The PropertySet objects make use of this mechanism to syn chronize only the properties that were modified The second advantageis that each DataField object caches its marshalled data that gets send to Flash clients Thus if two clients want to load the same property and it has not been modified between these two requests the cached value will be sent to the second client so that there is no performance penalty for remarshalling the value BooleanField extends DataField implements Cloneable Serializable The class corresponding to the boolean datatype in ActionScript Constructor Summary BooleanField String name boolean value 122 BooleanField Method Summary boolean getBoolean void setBoolean boolean newValue
38. ActionScript is a loosely typed language but the Oregano Client API is not When you pass an invalid datatype to a method of one of the objects in the O regano Client an error will be generated and sent to the server as a log entry There are very few exceptions for example the getValue method of the PropertySet object which can return any kind of datatype In these cases the return type is any If the method does not return anything the return type is void For arguments and return values of type Array the datatype for the elements of that array is indicated as follows Array String This example specifies an array that can only contain elements of type String Buddies This object manages a list of buddies Each user can have his own buddy list which will be stored in the database You obtain a reference to the Buddies object with org omus user getBuddies 44 Buddies Method Summary void addListener Object listener void insert String username void load void remove String username void removeAll void removeListener Object listener Event Summary onError Error error oninsert String username onLoad Array String usernames onRemove String username onRemoveAll addListener void addListener Object listener Adds the specified object as a listener for all the events the Buddies object can generate insert void insert String username Inserts a new user into the buddy list load
39. All Message msg Sends a message to all users who are currently logged into the server It will be passed to the messageToUser method in org omus ext GroupExtension for all the recipients and then forwarded to the clients and received in the onMessage event handler in the client side M essenger object sendToGroup void sendToGroup Message msg String groupName Sends a message to all the members of a particular group It will be passed to the messageToGroup method in org omus ext GroupExtension in the target group and then forwarded to the client and received in the onMessage event handler in the client side M essenger object 112 MessagingManager sendToUser void sendToUser Message msg String recipient Sends a message to one user It will be passed to the messageToUser method in org omus ext GroupExtension in the group that the user is currently member of and then forwarded to the client and received in the onMessage event handler in the client side M essenger object subscribe void subscribe User user String subject Subscribes the specified user to all messages with the specified subject unsubscribe void unsubscribe User user String subject Unsubscribes the specified user from all messages with the specified subject unsubscribeAll void unsubscribeAll User user Unsubscribes the specified user from all messages PropertySet implements Serializable Represents a collection of p
40. D The ID that will be used as a first parameter in every constructor for DbReader or DbWriter objects client side and server side rollbackOnError Boolean value Set this attribute to true if you want the transaction to be rolled back when this statement caused an error The transaction will simply be aborted if your database does not support transactions 38 dbCustom xml minRows Integer value This is an optional attribute For dbWriter nodes it is the required mini mum number of affected rows of the corresponding DELETE INSERT Or UPDATE state ment for dbReader nodes it is the required minimum number of rows in the result set If the actual number of rows is lower than specified the transaction will be rolled back or aborted if your database does not support transactions Child nodes statement Contains the SQL statement Oregano Server uses Prepared Statements so all the parameters are replaced by a in The in nodes specify all the parameters that will be passed to the statement N ote that the order of the in nodes must correspond to the order of question marks in your state ment out Can only be included in dbReader nodes Useful if the specified value is required as an in value in a subsequent statement The name attribute of an out node must correspond to one of the field names read by the statement See the section on the DbTransaction object in the Client API or Server API chapter for example co
41. DataFields of this D ataR ow DataTable extends DataField implements Cloneable Serializable The class corresponding to org omus Table in the Client API It does not have an updateRow method like the client side Table object because all modified rows will be updated automatically since all DataField objects keep track of changes Constructor Summary DataTable String name TableDefinition td DataTable String name DataTable dt 130 DataTable Method Summary void addAllRows DataTable source void addRow DataRow row Object clone TableDefinition getDefinition DataRow getRow int index Iterator iterator void removeAllRows DataRow removeRow int index int size void sort DataTable Comparator tableComp DataTable DataTable String name TableDefinition td Creates a new DataTable with the specified name and table definition DataTable DataTable String name DataTable dt Creates a new DataTable with the specified name and the same rows as the specified table addAllRows void addAllRows DataTable source Adds all rows of the specified table to this table This method will only succeed if both tables have matching table definitions addRow void addRow DataRow row Adds a single row to this table This method will only succeed if the specified DataR ow object matches the table definition See the entry for the match method in TableD efinition for details c
42. Email method of the User object changePassword Boolean value If set to true a client is permitted to change the password with the setPassword method of the User object changePermissions Boolean value If set to true a client is permitted to change the permissions with the setPermissions method of the User object lt groupConfig gt Contains one optional attribute one loginGroup child node and an unlimited number of optional group nodes Example lt groupConfig defaultExtension DefaultGroup gt lt loginGroup gt lt see loginGroup section gt lt loginGroup gt lt group gt lt see group section gt lt group gt lt group gt lt see group section gt lt group gt lt groupConfig gt defaultExtension Thename of the class to be used to extend the functionality of all groups This attribute is optional The specified class must implement org omus ext GroupExtension See the section on GroupExtension in the Server API chapter 30 lt groupConfig gt lt loginGroup gt Contains one optional attribute and no child nodes The login group is a special group that serves as an entrance hall Each user is member of this group after she logged in The login group is different from normal groups in that you cannot close this group cannot specify a user limit and cannot rejoin this group once you changed into another group Another important difference is that you are alone as a member
43. Loaded n E 5 gt a boolean isLoaded Returns true if the attachment of this mail has been loaded isUnread boolean isUnread Returns true if this mail is unread loadAttachment void loadAttachment Loads the attachment for this M ail object mark void mark boolean asRead M arks this M ail object as read or as unread Mail 65 remove void remove Removes this M ail object from its containing M ailbox object removeListener void removeListener Object listener Removes the specified listener from this object send void send String recipient Sends this M ail object to the specified recipient You can send the same M ail object to more than one user Each time you send a mail a copy of this M ail object will be placed into the out box object onError onError Mail mail Error error Event handler invoked when an error occured that was caused by one of the following methods of the M ail object send loadAttachment mark remove onLoadAttachment onLoadAttachment Mail mail Event handler invoked when the attachment has been loaded into this M ail object onMark onMark Mail mail Event handler invoked when this M ail object has been marked as read or as unread onRemove onRemove Mail mail Event handler invoked when this M ail object has been removed from its containing M ailbox object onSend onSend Mail ma
44. OREGANO MULTIUSER SERVER WWW OREGANO SERVER ORG REFERENCE MANUAL Version 1 1 0 REFERENCE MANUAL Version 1 1 0 written by Jens Halm Oregano Multiuser Server Reference Manual 2003 2004 Jens Halm Table of Contents 1 Feature Overview c cece cece eee en es 9 2 Installation 55 5532 io 11 Installing the Java Runtime Environment 11 Installing the JDBC driver ooooooocccccccccccc eee 12 Installing Oregano Server cc cece eee e eee eens 12 Creating the Oregano tables ooooooccom m o 12 Editing COMTE XML ri 13 Editing the start Script oooooooccccccnncccc co 14 Booting Oregano Server 0 cece cece eee e eee eens 14 3 Example Application 16 Installing and running the application 16 Examining the objects cece cece ee eee eee eee 17 LORIN a Ses aaies aad neg gated Sire ns REEERE NEE KERY EREA scores 17 ROOM td lt E nelee din 18 A Gira Shae eteom aihneiale Haat he Die Ges Sie este aiheeleld 20 Chatyo atte tke ita tove stale a O angiear momen tens 21 A Configuration vio road tes Reiss 22 config xml the main configuration file 22 OB lis 22 POS is a A tan ANS 23 KEXTENSIONS Ss traca eean oh Seale booked cea ah ae 23 KAGIMIND A A il 24 Table of Contents 5 SSELVEFGONTI OY sie oes ecco ge ete o aaa ds 25 KSEIVEDD ceras a de
45. Or syncGroupProperties methods in the GroupExtension class are only subsets of the original PropertySet objects containing only those properties that were modified In these cases you can use this method to obtain the parent object which contains all properties setErrorCode void setErrorCode String err Sets the error code of this instance to the specified string Useful if you want to abort a synchronization from within the syncUserProperties and syncGroupProperties methods in org omus ext GroupExtension and send a customized error code to the client O therwise a default error code would be sent RegistrationData extends AuthenticationData Contains registration data of a user Gets passed to the prepareRegister method in org omus ext LoginExtension It inherits all the methods of Authentication data It adds two methods to handle the email address of the user 116 RegistrationData Method Summary String getEmail void setEmail String newMail getEmail String getEmail Returns the email address of the user setEmail void setEmail String newMail Sets the email address of the user to the specified string Services A static utility class to retrieve instances of one of the M anager classes Method Summary static LogManager getLogManager static MessagingManager getMessagingManager static TaskManager getTaskManager getMessagingManager static MessagingManager getMessagingMana
46. The login object registers itself with the Session object in its constructor org omus session addListener this The login object handles all four events that the Session object can generate The onLogin and onRegister event handlers both call the init method where a bunch of listeners are registered with the corresponding objects because many of the objects available in the org omus namespace will not be created until the user has successfully logged in LoginObj prototype init function org omus group addListener _root room org omus info addListener _root room org omus messenger addListener _root chat org omus info loadGroupList popup hide _root gotoAndStop 4 In addition the onR egister event sets the avatar property to the string identifier for the avatar that the user had chosen LoginObj prototype onRegister function extraData this init var ps org omus user getProperties ps setValue avatar this chosenAv ps synchronize Example Application 17 gt 5 ack gy Ea o E a dwex3 The configuration for the avatar property in config xml looks like this lt userProp name avatar type string persistence writeOnChange cacheLevel synchronizeGroup gt Since the attribute persistence is set to writeOnChange the new value is automatically stored in the database through the command ps synchronize The attribute cacheLevel is set to synchronizeGroup so that t
47. ULL DbTransaction object was empty execution of one or more statements denied group does not exist group cannot be created group is closed user limit of group reached joining this group not permitted login group cannot be opened or closed client not owner of this lock changing email address not permitted changing password not permitted changing permissions not permitted illegal value for setting user permissions mailbox limit exceeded mail in out box cannot be marked as read mail rejected blacklist of recipient contains sender 92 Error codes bud 001 buddy list already contains this user buddy list did not contain this user one or more properties do not exist datatype of one or more properties does not match configuration synchronization rejected by custom server extension logout requested by custom server extension logout forced by administrator server switched to debug mode bud 002 bud 003 limit of buddy list exceeded prp 001 prp 002 prp 003 prp 004 PropertySet no longer valid prp 005 changing groups failed 1gt 001 logout requested by client lgt 002 1gt 003 1gt 004 user was banned 1gt 005 1gt 006 server shutdown 1gt 007 connection broken List of methods that can cause an onError event Method Buddies insert Buddies load Buddies remove Buddies removeAll DbTransaction execute Group change Group close Group open Locks release Mail loadAttachment Mail mark Mail remove Mai
48. a configID attri bute in a lt dbWriter gt node in dbCustom xml The specified resultID can be used to check the number of affected rows in the DbResult object 146 DbWriter 147 148
49. an isClosed Returns true if the group is closed so that no other users can join isFull boolean isFull Returns true if the maximum number of users has been reached open void open Opens the group for other users to join sendToClients void sendToClients Message msg Sends the specified M essage to all the clients in this group The message will be received in the onMessage event handler in the client side M essenger object sendToClients void sendToClients Message msg User exclude Sends the specified M essage to all the clients in this group except for the specified user The message will be received in the onMessage event handler in the client side M essenger object GroupCreationData Contains information about a group that is going to be created Gets passed to the prepareGroupCreation method in org omus ext GroupExtension 106 GroupCreationData Method Summary String getConfigID String getErrorCode String getName void setErrorCode String newCode getConfiglD String getConfigID Returns the configlD of the group It identifies the lt group gt node in config xml that was used to configure this group You can have an unlimited number of groups with the same configlD but different names See the Configuration chapter for more details getErrorCode String getErrorCode Returns the error code or null if none was specified yet getName String g
50. ange into another group or to obtain the PropertySet objects of the group or a user currently in the group User Represents the user that was logged in with this client Other users of the current group are represented through their PropertySet objects Messenger Message MessageFilter Use these object to easily exchange data between clients or between a client and the server PropertySet PropertyLoader These objects manage the properties associated with a group or a user The PropertySet object handles all the persistence and synchronization requirements according to the configuration in config xml 40 Overview Table TableDefinition Class Table is an additional datatype that can be used as a property Useful if you want to manage and synchronize large amounts of data since it can be partially synchronized Use the Class object to register your own custom ActionScript objects so that they can be used in Properties or M essages Mailbox Mail Buddies Info Locks Utility classes Integrate email functionality into your application easily manage the user s buddy list or use the Info object to load a list of all users currently online or a list of all groups that were created Or use the Locks object to lock objects in the cur rent group in a synchronied way DbTransaction DbWriter DbReader DbResult Use these objects to read or write data to or from the database without the need to write server side code Log Error
51. asket In other words If foo is the name of a property configured as a counter then setValue foo 4 called in PropertySet in the client means subtract 4 from the current value and only the relative change is submitted to the server Constructor Summary CounterField String name int initialValue CounterField 123 e ep snwo si0 Method Summary void add int dif int get void reset void set int newValue CounterField CounterField String name int initialValue Creates a new CounterField with the specified name and initial value add void add int dif Adds the specified value to the int value of this CounterField N egative values are per mitted get int get Returns the current value of this CounterField reset void reset Resets the value of this CounterField to the initial value set void set int newValue Sets the value of this CounterField to the specified value DataField implements Cloneable Serializable The abstract superclass of all DataFields Method Summary void accept FieldVisitor fv void addListener FieldListener fl Object clone 124 DataField String getName void removeListener FieldListener fl accept void accept FieldVisitor fv Accepts a visitor The visitor pattern is useful if you want to extend the functionality of all DataFields without modifying their API addListener void addListener Fi
52. ate Array Object org omus Table If you set a parameter in the DbTransaction object it is available to all the DbWriter or DbReader parts you add to this transaction If you want to set parameters that can only be read by one particular DbWriter or DbReader object you must use the setParam method of those objects addPart void addPart DbReader DbWriter part Adds a DbReader or DbWriter object to this transaction 50 DbTransaction execute void execute Executes this transaction The result will be passed to the onResult event removeListener void removeListener Object listener Removes the specified listener from this object onError onError Error error Event handler invoked when an error occured that was caused by the execute method of this object onResult onResult DbResult result Event handler invoked when the result of the transaction has been received a E 5 gt a DbWriter This object represents a DELETE INSERT Or UPDATE statement to be executed on the server Constructor Summary new DbWriter String configlD String resultID Method Summary void setParam String name any value DbWriter new org omus DbWriter String configID String resultID Creates a new DbWriter object The specified configlD must match a configlD attribute in a lt dbWriter gt nodein dbCustom xml The optional resultlD must be specified if you want to check the number
53. be overwhelmed with all the configuration options and the number of objects in the API The small example application that you can download from www oregano server org might serve as an easy to grasp starting point for your own applications Installing and running the application 1 Download the example application from www oregano server org and unzip it 2 Moveconfig xml from the config directory of the server runtime directory to a safe place so that you can put it back later 3 Open config xml included with the example application download This configu ration file is prepared for use with the example You only need to add the infor mation that is specific to your machine 4 Set the address attribute of the server node inside the serverConfig node The address can be an IP address or the human readable name ie www myserver com 5 Edit the following four attributes in the database node url driver userID password If you are not sure how to do this see the Configuration chapter for details 6 Save the file and copy it to the config directory of your server runtime directory 7 Reboot Oregano Server 8 Open login as in the example _as directory and edit the first line Set the second parameter of the init method to the server address that you specified in config xml or to localhost if client and server run on the same machine 9 Open examplefla and start it with Test M ovie from the Control menu 10 Click on n
54. case the most appropi ate setting for each category is warn For 10 of these 12 categories log entries will be written by the server automatically The only exceptions are client_dev and extensions The former is the category that con tains all log entries that you sent from a client using one of the methods of the Log object in the Client API The latter contains all log entries that you created through call ing one of the methods of the LogM anager in the Server API See the corresponding chapters for more details on logging dbCore xml SOL used by Oregano Server This configuration file contains all SQL statements that are used by the O regano Server It has been tested with M ySQ L If you use another database it may be possible that you have to adjust some of the SQL statements Especially the JOIN syntax may differ in other database systems Please do not modify any other nodes than the statement nodes If you managed to adjust this configuration file for a different database feel free to send it to info oregano server org dbCustom xml custom SOL statements All the SQL statements that you want to use either with the ActionScript DbTransaction object of the Client API or the DbTransaction class of the Server API have to be con figured in this file There are two types of top level nodes dbReader and dbWriter The former is intended for SELECT statements the latter for UPDATE INSERT Or DELETE state ments Attributes configl
55. created groups will be removed automatically when the last user leaves the group groups created at startup will be removed when the server shuts down The value will be stored in the database Each modification will be written to the database immediately The fields required to store the properties will be created automatically in the tables userprops Or groupprops respectively On the other hand if you remove a property from the configuration file the corresponding column will not be removed in the data base thus you do not risk losing data if you boot Oregano Server with the wrong con figuration file by mistake The logging table will include an entry with a list of all columns that are obsolete so that you can delete them manually 34 lt groupProp gt cacheLevel M ust be one of the following values off serverCache synchronizeGroup lt userProp gt The value will not be cached in the clients nor in the server It has to be read from the database each time it is accessed from client side or server side code with the load methods of the PropertySet object The value will be loaded into the PropertySet object of the corresponding Group object in the server This way you have quick access to the value if you write a server extension that reads or modifies the value frequently The value will not be loaded into any client thus the client side PropertySet objects must load the value from the server side object explicit
56. ct lis onSynchronize function newProps clientRequest if newProps contains position var pos newProps getValue position var newXpos pos x var newYpos pos y move avatar to new position t J add this listener to the PropertySet object of each user Before you can use the position property you must define it in config xml lt globalProperties gt lt userProp name position type object persistence off cacheLevel synchronizeGroup gt lt other properties gt lt globalProperties gt The persistence setting is off because if the user logs out nobody is interested in remembering her last position The cachel evel is set to synchronizeGroup so that the value is synchronized in all clients of the group automatically The org omus namespace The namespace org omus is used for all the objects that are created automatically It is attached to the global object in Flash 6 players and to MovieScript prototype in Flash 5 players This way it can be referenced the same way in both players The Session object for example is one of these singletons and thus can be referenced with org omus session Three objects will be created immediately when you include init as org omus session org omus clazz org omus log The session object is used to connect to the server and the class object is used to regis ter your own custom ActionScript classes so that they can be exchanged between
57. d loadAttachment void mark boolean asRead void remove void removeListener Object listener void send String recipient Event Summary onError Mail mail Error error onLoadAttachment Mail mail onMark Mail mail onRemove Mail mail onSend Mail mail new new org omus Mail String subject Constructs a new M ail object with the specified subject addListener void addListener Object listener Adds the specified object as a listener for all the events the M ail object can generate getAttachment Object getAttachment Returns the attachment of this mail object or null if the attachment has not been loaded into the client yet It is a plain ActionScript object that is empty in a newly cre ated M ail object You can add properties with one of the following datatypes boolean number String Date Array Object org omus Table getDate Date getDate Returns an ActionScript Date object representing the time this M ail object was sent 64 Mail getMailbox org omus Mailbox getMailbox Returns one of the two M ailbox objects that this mail belongs to getRecipient String getRecipient Returns the recipient of this M ail object M ay return nu11 if it isa new M ail object that has not been sent yet getSender String getSender Returns the sender of this M ail object getSubject String getSubject Returns the subject of this M ail object is
58. de lt dbWriter configID updateCat rollbackOnError true minRows 1 gt lt in name color gt lt in name catID gt lt statement gt UPDATE cats SET color WHERE catID lt statement gt lt dbWriter gt lt dbReader configID loadCat rollbackOnError true gt lt in name catID gt lt statement gt SELECT FROM cats WHERE catID lt statement gt lt dbReader gt dbCustom xml 39 a o El oq c y fag o 5 CHAPTER 5 Client API Overview The Client API is fully object oriented Each method and each event handler of each object is explained in the Reference section of this chapter To use the Client API you must include it in your Flash M ovie Copy the oregano_as directory of your Oregano Client download into the directory of your Flash file Then add the line include oregano_as init as to your movie Right after the include statement it is advisable to initialize the Session object with a line like this now org omus session init vers 2 12 www myserver com 1655 For more details see the section on the Session object in the Reference part of this chap ter org omus is the namespace for all Oregano objects To give you an overview of the Client API here is a full list of all objects Session Handles the connection to the server Use this object to log in and log out a user Group Represents the current group Contains methods to close a group to ch
59. ding void sortBySender boolean ascending void sortBySubject boolean ascending Event Summary onError Error error onLoad Mailbox box onNewMail Mailbox box onRemoveAll Mailbox box addListener void addListener Object listener Adds the specified object as a listener for all the events the M ailbox object can gener ate Mailbox 67 a s gt 2 load void load Loads all M ail objects without their attachments that have not been loaded yet getLoaded int getLoaded Returns the number of loaded M ail objects in this mailbox getMail Mail getMail int index Returns the M ail object at the specified index The mails are sorted by date per default in this case the latest mail will be at index position O But you can change the order with one of the sort methods getTotal int getTotal Returns the total number of M ail objects in this mailbox getType String getType Returns either inBox or outBox getUnread int getUnread Returns the number of unread M ail objects in this mailbox removeAll void removeAll Removes all M ail objects from this mailbox removeListener void removeListener Object listener Removes the specified listener from this object 68 Mailbox sortByDate void sortByDate boolean ascending Sorts all M ail objects by date sortBySender void sortBySender boolean ascending
60. e specified number of seconds elapsed To disable caching set the value to o groupListinterval The length of the interval in seconds The server sends the list of groups to all clients at regular intervals It will be passed to the onLoadGroupList event handler of the Info object in the client Set the value to o if you want to disable this feature and load the list of groups by hand with the loadGroupList method of the Info object userListCache The number of seconds the list of users will be cached You can load the list with the loadUserList method in the Info object of the client If you enable caching the server will cache the message containing the list of users for subsequent requests until the spec ified number of seconds elapsed To disable caching set the value to o userListInterval The length of the interval in seconds The server sends the list of users to all clients at regular intervals It will be passed to the onLoadUserList event handler of the Info object in the client Set the value to o if you want to disable this feature and load the list of users by hand with the loadUserList method of the Info object lt services gt 29 lt permissions gt Contains three required attributes and no child nodes Example lt permissions changeEmail true changePassword true changePermissions false gt changeEmail Boolean value If set to true a client is permitted to change the email address with the set
61. e Class object is a singleton that will be created automatically You can reference it with org omus clazz 46 Class Method Summary Function getConstructor String name void register String name Function constructor getConstructor Function getConstructor String name Returns the constructor that was registered with the specified name register void register String name Function constructor Registers the specified constructor with an arbitrary name DbReader This object represents a SELECT statement to be executed on the server Constructor Summary new DbReader String configID String resultID Method Summary void setParam String name any value DbReader new org omus DbReader String configID String resultID Creates a new DbReader object The specified configlD must match a configlD attribute in a lt dbReader gt nodein dbCustom xml The optional resultID must be specified if you want to read values from the DbResult object The same resultID must then be passed to the getField or getTable methods of the DbResult object The resultlD is necessary because you can include an unlimited number of DbReader objects in a single DbtTransaction object setParam void setParam String name any value Sets the parameter with the specified name to the specified value The name of the parameter must match the name attribute of one of the lt in gt nodes you specified in the dbCustom x
62. e Client API Method Summary boolean addCommand Command com void close Iterator getAllUsers String getConfigID String getName PropertySet getProperties User getUser String name int getUserCount int getUserLimit boolean isClosed boolean isFull void open void sendToClients Message msg void sendToClients Message msg User exclude addCommand boolean addCommand Command com Adds the specified command to the queue of this group for later execution You will rarely need this method because all of the methods that are invoked in your GroupExtension get executed in the group queue anyway All groups in the Oregano Server are single threaded M any methods of the Group User and PropertySet classes are protected against access from other threads because they are not synchronized If there is a time consuming task that you delegated to a worker thread with one of the methods of the TaskM anager you cannot call these methods from within that task So if you use the TaskM anager to read from the database for example and want to use the values that you read to modify the properties of a user you have to write a com mand that performs this task and put it into the group queue Example code migth look like this final String result null Command com1 new Command public void execute result aTimeConsumingCalculation Command com2 new Command 4 public void execute
63. e M essage object used to send data to clients is included in this package too org omus db Contains classes to read and write to and from the database They are very similar to the corresponding objects in the Client API N ote that persistent properties will be writ ten to the database automatically You only need these classes if you created additional tables in the database Package org omus ext Contains five interfaces that you can use to develop extensions for the O regano Server Each extension must implement one of these five interfaces and the corresponding class name must be specified in config xml so that the server can load the extension GroupExtension Interface This is the main interface of the org omus ext package you can use it to build custom groups or rooms It contains a set of methods that get invoked when a special event occured All groups in the Oregano Server are single threaded so you do not need to care about synchronization issues There is no need to create your own threads or Timer instances If there is a time consuming task you can delegate it to a pool of worker threads with one of the methods of the TaskM anager 96 GroupExtension There are two places in config xml where a GroupExtension can be specified The defaultExtension attribute of the enclosing lt groupConfig gt node and the extension attribute of each particular lt group gt node The former is useful if you want to add fea tures
64. e properties of this user which will be written to the database after this method executed LogoutExtension 101 x snwo 310 PasswordDecoder Interface Provides a method to decode an encrypted password This extension must be used together with a K eyGenerator extension You must specify the name of the class that implements this interface in the lt extensions gt node in config xml Method Summary String decode String password String secretKey decode String decode String password String secretKey Invoked when a user will be logged in the specified password was encoded by the client this method must return the decoded password using the specified key which is the same that was used by the client to encode the password Package org omus core Contains the core classes of the Oregano Server Group User and PropertySet are class es that are very similar to their client side twins of the same name Use these objects to read and modify properties and to send messages to clients Furthermore this package contains a lot of additional utility classes AuthenticationData Contains authentication data of a user Gets passed to the prepareLogin method in org omus ext LoginExtension Method Summary String getErrorCode String getPassword String getUsername void setErrorCode String newCode void setPassword String newPassword void setUsername String newName getErrorCode String getErr
65. e wat SAA AA oe ees eek 26 lt database gt cis een Se BOER Eee Set REE EEE ees 27 lt typeMap gt 2 de 28 lt STAUISTICS rn as 28 ISRIMICOS ia a a ale diane 29 Permission A a Eds 30 KBIOUPCONTIS gt setos A ati 30 lt lOBiNGOUP gt o A A 31 LENAT oD AEE EE EEE or maha T 32 EPTOPertIES mito roo R Hee a A A 32 lt globalProperties gt cv oo ccoo ca aa 33 lt groUpPrOpP gt iii ii 33 CUSEMPIOP gt eden A A ose 35 lt tableDefinition gt virpi T e E R E 36 lt KCOIUMND aoe A ad a TA ee 37 CIO BS Wiens pa ida dona es 37 dbCore xml SOL used by Oregano Server 38 dbCustom xml custom SOL statements 38 By CHENUARN A early roneteanets Meares 40 Overview iii id 40 Event Model oc ii 41 Exchanging data 0 a ii 42 The org omus namespace oooocccccccccncnnnccncnn ooo 43 Reference in 44 BUGGIES a as 44 q oie ess Aled nds Sees ERA CRS ane CUE Sika ee th 46 DDR Ade caper a a ee 47 DBReSullts e es Se OR ERAS es BE ot 48 DbTransaction soros see ee eee Ree ea dis 48 DBD Writer acia ari 51 6 Table of Contents Group clarita ardid did 53 O a e e de A ope 56 A hori Sok eee ey Gales 3 oho eee E eae Noes 58 LOR it eo it de 61 Ma di tas 63 Mailbox ai 67 Message it dd dad 70 Me ssagebilter acia A ias 71 Messenger esseri stat a aS 72 Propertylo der aiii is eii 75 PEOPpE Ed Ai 77 OM a a Aa 81 A Ae ON Eia E EAEE AR EONAR 83 TableDefinition ee a r E r Se a 87 Us E E E eee se EE E E E EE 88 Error codes aa ea
66. e with closed connections You should find the URL format for your driver in the documentation that comes with it driver The fully classified class name of your driver e g org gjt mm mysql Driver Make sure that the Driver is located in the lib ext directory of your JRE userlD The user ID that should be used to connect to the database Installation 13 5 a e y a n o s password The password that should be used to connect to the database Editing the start script If you run Oregano Server on Linux you have to edit start sh For Windows the start script is named start bat Both are included in the Oregano server runtime directory On Linux you have to set the file permissions to make it executable chmod 770 start sh Open the script in a text editor and add values for the six variables SERVER_ADDRESS The address of the server Must match the address attribute of the corresponding server node in config xml SERVER_TYPE Can take one of the following values Standalone The server runs on a single machine Primary This server is the primary server of a cluster Only one machine can act as the primary server Secondary This server is one of an unlimited number of secondary servers in a cluster If you want to usethe config xml that was included in the O regano download the value must be Standalone PRIMARY_ADDRESS The address of the primary server This variable is only required in the start script
67. eldListener fl Adds a listener to this DataField that gets notified when the value of this object was modified clone Object clone Returns a clone of this DataField getName String getName Returns the name of this DataField removeListener void removeListener FieldListener f1 Removes the specified listener from this DataField DataList extends DataField implements Cloneable Serializable The class corresponding to the Array object in ActionScript When an array is sent to to the server it will be converted to a DataList instance and each element of the array is converted to the corresponding D ataField Constructor Summary e ep snwo si0 DataList String name DataList String name DataList source DataList 125 Method Summary void add DataField df void add int index DataField df void addAll DataList list void addAll int index DataList list Object clone DataField get int index Iterator iterator DataField remove int index void removeAll int size void sort DataList Comparator listComp DataList DataList String name Creates a new DataList with the specified name DataList DataList String name DataList dl Creates a new DataList with the specified name and the same DataFields as the speci fied DataList add void add DataField df Appends the specified DataField to the end of this list add void add int index
68. er of columns in this table definition getColumnName String getColumnName int index Returns the name of the column at the specified index position getColumnNames String getColumnNames Returns an array of all column names in the order they were added to this TableD efinition getColumnType Class getColumnType int index Returns the type of the column at the specified index position matches boolean matches DataRow row Returns true if the specified DataRow matches this table definition The number of DataFields contained in the specified DataRow must match the number of columns in this definition object and each DataField of the specified DataRow must have a match ing name and datatype in this definition object 140 TableDefinition Package org omus db Contains classes for database connectivity Can be used for reading and writing DataField objects from and to the database DbException implements Serializable Thrown when an error occurs during execution of a transaction You will rarely create a DbException object yourself but many methods in the O regano Server API throw this Exception which you have to catch in your extensions You can use the getMessage method inherited from Throwable to obtain the client side error code of this Exception See the section on error codes at the end of the Client API chapter for a list of possible error codes Constructor Summary DbException Stri
69. error String errorCode Exception e void error String errorCode Exception e String info boolean errorEnabled void info String errorCode void info String errorCode String info void info String errorCode Exception e void info String errorCode Exception e String info boolean infoEnabled void warn String errorCode void warn String errorCode String info void warn String errorCode Exception e void warn String errorCode Exception e String info boolean warnEnabled debug void debug String errorCode Creates a log entry with the specified error code if the LogM anager is configured to process messages of level DEBUG or higher The error code will be automatically prefixed with ext to avoid confusion with built in error codes debug void debug String errorCode String info Creates a log entry with the specified error code and info string if the LogM anager is configured to process messages of level DEBUG or higher The error code will be auto matically prefixed with ext to avoid confusion with built in error codes debug void debug String errorCode Exception e Creates a log entry with the specified error code and the stackTrace of the specified Exception if the LogM anager is configured to process messages of level DEBUG or higher 108 LogManager The error code will be automatically prefixed with ext to avoid confusion with built in error codes debug
70. etName Returns the name of the group setErrorCode void setErrorCode String newCode Sets the error code to the specified string The code will be prefixed with cld auto matically to avoid confusion with built in error codes It will be sent to the client if the prepareGroupCreation method in org omus ext GroupExtension returns false so that the creation of the group will be aborted LogManager Contains methods to create custom log entries in the logging table on the server The object uses four different log levels DEBUG INFO WARN and ERROR A log level is an indi cation of the importance of a message Depending on the mininum log level you speci fied for the lt extensions gt node in the logging section in config xml a log entry might be ignored or written to the database o El ga o 3 S wv a o 2 5 If the configuration looks like this lt extensions level warn gt LogManager 107 all log entries of level waRN or higher will be written to the database or to a file depend ing on the configuration Accordingly calling one of the debug or info methods in LogM anager will be ignored in this case Method Summary void debug String errorCode void debug String errorCode String info void debug String errorCode Exception e void debug String errorCode Exception e String info boolean debugEnabled void error String errorCode void error String errorCode String info void
71. ew user choose an avatar and on the next screen choose a nick name and a password and click OK 11 Enter one of the four rooms by clicking on the small map in the upper right cor ner 12 You can try out one of the three features of this application enter text into the field at the bottom and press return to send the message move your avatar to a new position by clicking on the stage change into another room by clicking on the small map in the upper right cor ner 16 Example Application This is all you can do with this application You might want to start a second client to see how it works with multiple connected users Please note that this is a very simple application that was developed to show how the core pieces of the Client API can be used to build a simple graphical chat application It does not for example handle any kind of depth sorting for the avatars in the rooms because these kind of features are not related to the Oregano API Examining the objects You can have a look at the source code of the example application in the include files in the example_as directory The most important parts will be explained in the next sec tion Login The login object with methods for login and registration is included in login as The first line initializes the Session object which is one of the singletons that are creat ed automatically in the org omus namespace org omus session init example localhost 1655
72. execute Please note that the second statement has 4 lt in gt nodes Three of them street city and phone will be set by your ActionScript code The last one userID will be set auto matically because it is configured as an lt out gt value in the first statement which will be available to all subsequent statements The attribute minRows is set to 1 in the first statement so that execution of the transaction will be aborted if the result is empty because the second statement would fail anyway if no user with the specified name exists DbTransaction 49 a E 5 gt 2 Constructor Summary new DbTransaction Method Summary void addListener Object listener void addPart DbReader DbWriter part void execute void removeListener Object listener void setParam String name any value Event Summary onResult DbResult result onError Error error DbTransaction new org omus DbTransaction Creates a new DbTransaction object addListener void addListener Object listener Adds the specified object as a listener for all the events the DbTransaction object can generate setParam void setParam String name any value Sets the parameter with the specified name to the specified value The name of the parameter must match the name attribute of one of the lt in gt nodes you specified in the dbCustom file The value can be one of the following datatypes boolean number string D
73. fied object must match the number of columns in this definition object and each property of the specified object must have a matching name and datatype in this definition object User The user object represents the user that was logged in with this client All other users who are currently member of the group are represented by their PropertySet objects instead The User object is a singleton that will be created automatically when a user logs in It can be referenced with org omus user Method Summary void addListener Object listener Buddies getBlacklist Buddies getBuddies String getEmail Mailbox getInBox Locks getLocks String getName Mailbox getOutBox String getPassword int getPermissions PropertySet getProperties 88 User void removeListener Object listener void setEmail String newEmail void setPassword String newPassword void setPermissions int newPermissions Event Summary onError Error error onSetEmail onSetPassword onSetPermissions addListener void addListener Object listener Adds the specified object as a listener for all the events the User object can generate getBlacklist Buddies getBlacklist Returns the Buddies object that represents the blacklist for this user This method is new in Oregano 1 1 0 If a user adds another user to his blacklist he will not receive any M ail objects sent by that user The blacklist returned by this
74. g example illustrates how you can use the DbTransaction object to read a user ID from one table and use that ID to change a value in another table without con tacting the server twice The corresponding entries in dbCustom xml might look as follows see the Configuration chapter for more details 48 DbTransaction lt dbReader configID readUserID rollbackOnError true minRows 1 gt lt in name username gt lt out name userID gt lt statement gt SELECT userID FROM reginfo WHERE username lt statement gt lt dbReader gt lt dbWriter configID updateAddress rollbackOnError true gt lt in name street gt lt in name city gt lt in name phone gt lt in name userID gt lt statement gt UPDATE address SET street city phone WHERE userID lt statement gt lt dbWriter gt The ActionScript code to execute those statements looks as follows var ta new org omus DbTransaction ta addPart new org omus DbReader readUserID ta addPart new org omus DbWriter updateAddress address ta setParam username Thomas ta setParam street 217 Mulholland Drive ta setParam city Los Angeles ta setParam phone 27 27 55 55 var lis new Object lis onResult function result trace affected rows result getAffectedRows address lis onError function error trace ERROR error getDescription ta addListener lis ta
75. ger Returns the M essagingM anager getTaskManager static TaskManager getTaskManager Returns the TaskM anager getLogManager 3J0 SNUWO B0 static LogManager getLogManager Returns the LogM anager Services 117 TaskManager A facility to schedule tasks for future execution in a background thread Tasks may be scheduled for one time execution or for repeated execution at regular intervals Some of the methods of TaskM anager simply delegate the specified TimerTask to the encap sulated Timer instance O thers require a Command object to be specified and are an extension to the functionality found in java util Timer You should avoid to create your own threads or Timer instances it may prevent the cor rect shutdown of the Oregano Server Method Summary void cancel Command com void executeDaily Command com void executeMonthly Command com int daylnMonth void executeNow Command com void executeWeekly Command com int daylnWeek void schedule TimerTask task Date time void schedule TimerTask task Date firstTime long period void schedule TimerTask task long delay void schedule TimerTask task long delay long period void scheduleAtFixedRate TimerTask task Date firstTime long period void scheduleAtFixedRate TimerTask task long delay long period cancel void cancel Command com Cancels regular execution of the specified Command executeDaily void
76. hange method of org omus group is called RoomObj prototype onClick function instName if instName main click on main stage gt move avatar if org omus group getName login return var x _root main _xmouse var y _root main _ymouse x Math max x 41 x Math min x 375 y Math max y 155 y Math min y 315 var ps Org omus user getProperties ps setValue position x x y y 3 ps synchronize else click on map gt change into new room if instName org omus group getName return var x parseInt Math random this xRange 41 var y parseInt Math random this yRange 155 var ps Org omus user getProperties ps setValue position x x y y 3 org omus group change instName null true Example Application 19 gt 5 ack gy Ea o E a dwex3 And finally when the group list was loaded into the client the corresponding event handler updates the four numbers in the map in the upper right corner Room0bj prototype onLoadGroupList function groups var 1 groups size for var i 0 i lt 1 i var row groups getRow i var cnt row userCount if row name login map num_ row name cnt This event handler gets called because the room object was registered as a listener with the org omus info object in the init method of the login object Avatar The Avatar object is included in avatar as It has two pro
77. he second 80 PropertySet argument is true if the onSynchronize event is the result of a call to PropertySet synchronize in this client It is false if the event was caused by another client or by the server Session This object is used to connect to the server The Session object is a singleton that will be created automatically It can be referenced with org omus session Method Summary void addListener Object listener void init String versionID String address int loginPort int reconnectPort boolean isConnected void login String username String password void logout void register String username String password String email void removeListener Object listener boolean setPasswordEncoder Function encoder Event Summary ONError Error error onLogin Object data onLogout Error error onRegister Object data addListener void addListener Object listener Adds the specified object as a listener for all events the Session object can generate init void init String versionID String address int loginPort int reconnectPort This method must be called before any attempt to login or register a user It is best placed right after the include oregano_as init as statement versionID is an arbitrary string that must match the versionID attribute of the login node in config xml on the server It can be used to prevent that someone uses a deprecated version of your client applicati
78. he value is loaded into all the clients of the current group automatically because the other clients need to know the value to show the corresponding avatar on the stage The actual connect function is quite simple In case of a registered user it calls org omus session login username password For a new user the following method is called org omus session register username password Since this application does not require that an email address is specified the third parameter is an empty string The onLogout and onError event handlers do only create the appropiate popup mes sage Room The Room object with methods for changing groups and moving avatars is included in room as When you click on the map in the upper right corner of the stage the avatar will move into another room Since the room object was registered as a listener with the org omus group object in the init method of the login object it contains methods that handle the events that the group object can generate The onChange event handler is invoked when the user has joined another group Room0bj prototype onChange function extraData remove users of the old room for each in this users this users each remove create all users of the new room this users new Object var ar org omus group getAllUserProperties for var i 0 i lt ar length i var propSet ar i var av new _root AvatarObj propSet this depth
79. id loadUserList void removeListener Object listener Event Summary onError Error error onFindUser String username String groupName onLoadGroupList Table groups onLoadUserList Array String usernames addListener void addListener Object listener Adds the specified object as a listener for all the events the Info object can generate findUser void findUser String username Locates the user with the specified name The onFindUser event handler will return the name of the group that the user with the specified name is currently member of or null if the user is offline loadGroupList void loadGroupList Loads a table containing all the groups that were created on the server If you need the list of groups in regular intervals you can set groupListInterval in the lt services gt node in the server configuration to the number of seconds between updates In this case you do not need to call this method the onLoadGroupList event handler will be called automatically loadUserList void loadUserList Loads an array of the names of all users that are currently logged in If you need the list of users in regular intervals you can set userListInterval in the lt services gt node in the server configuration to the number of seconds between updates In this case you do not need to call this method the onLoadUserList event handler will be called auto matically Info 57 a E 5 gt a
80. il Event handler invoked when a Mail object has been sent successfully N ote that the argument is a copy of the original M ail object the one you invoked the send method 66 Mailbox on This copy was put into the out box because the original M ail object could have been sent to multiple recipients Mailbox The M ailbox object stores M ail objects which are different from M essage objects in that they are persistent If you send a M ail object to a user who is currently offline the M ail object will be delivered automatically the next time the recipient logs in Each client has two Mailbox objects one for the out box and one for the in box Use the methods of the User object to obtain a reference to a M ailbox object This object is intended to implement some kind of email functionality in your multiuser application If you need to send messages to exchange data between clients or between a client and the server as a requirement of your application logic use M essage objects which are similar to M ail objects They differ in that they are not persistent and that they can be sent not only to a user but also to a group to all users currently online or to a server extension Method Summary void addListener Object listener void load int getLoaded Mail getMail int index int getTotal String getType int getUnread void removeAll void removeListener Object listener void sortByDate boolean ascen
81. ionPart tap DbResult execute throws DbException void setAllParams DataRow dr void setParam DataField df int size DbTransaction DbTransaction Creates a new DbTransaction object add void add DbTransactionPart tap Adds a DbWriter or DbReader object to this transaction execute DbResult execute throws DbException Executes this transaction and returns the result setAllParams void setAllParams DataRow dr Adds all DataFields contained in the specified DataRow as a parameter to this DbTransaction The name of each DataField must have a matching name attribute in one of the lt n gt nodes you specified in the dbCustom xml file If you set parameters in the DbTransaction object they are available to all the DbWriter or DbReader parts you add to this transaction If you want to set parameters that can only be read by one par ticular DbWriter or DbReader object you must use the setParam method of those objects 144 DbTransaction setParam void setParam DataField df Adds the specified DataField as a parameter to this DbTransaction The name of the DataField must match the name attribute of one of the lt in gt nodes you specified in the dbCustom xml file If you set a parameter in the DbTransaction object it is available to all the DbWriter or DbReader parts you add to this transaction If you want to set parameters that can only be read by one particular DbWriter or DbReader object yo
82. is message Unlike all the other send methods this one does not deliver the message to another client sendToUser void sendToUser Message msg String username boolean sameGroup Sends a message to one user If the third parameter is true the message will only be deliv ered if the recipient is currently member of the same group subscribe void subscribe String subject Subscribes to all messages with the specified subject unsubscribe void unsubscribe String subject Unsubscribes from all messages with the specified subject unsubscribeAll void unsubscribeAll Unsubscribes from all messages onError onError Error error Event handler invoked when an error occured onMessage onMessage Message msg Event handler invoked when a message is received that has no filter applied to 74 Messenger onSubscribe onSubscribe String subject Event handler invoked when messages with the specified subject have been subscribed onUnsubscribe onUnsubscribe String subject Event handler invoked when messages with the specified subject have been unsub scribed onUnsubscribeAll onUnsubscribeAll Event handler invoked when all messages have been unsubscribed PropertyLoader The PropertyLoader object is only needed for properties of users who are not member of the current group or for properties of groups other than the current group It can even be used for
83. issions onSetPermissions Event handler invoked when the permission value was modified and written to the database User 91 n 5 taa gt ar Error Codes Error descriptions ses 001 ses 002 ses 003 ses 004 ses 005 ses 006 ses 007 ses 008 ses 009 ses 010 ses 011 ses 012 msg 001 msg 002 msg 003 dbe 001 dbe 002 dbe 003 dbe 004 dbe 005 dbe 006 dbe 007 dbe 008 dbe 009 dbe 010 dbe 011 dbe 012 dbe 013 dbe 014 cgr 001 cgr 002 cgr 003 cgr 004 cgr 005 grp 001 grp 003 usr 001 usr 002 usr 003 usr 004 mbx 001 mbx 002 mbx 003 internal server error maximum number of connections exceeded login denied by custom server extension wrong client versionID server in debug mode or preparing for shutdown user already logged in user with given nick name already exists user is banned user with given email address already exists user with given email address is banned incorrect login no connection to server unknown message type error parsing message missing server extension for handling outgoing message unable to connect to database database error SOL error less than the required minimum of rows in the result set less than the required minimum of affected rows user is banned user does not exist group does not exist missing lt in gt parameter missing lt out gt parameter type of transaction part does not match configuration cannot handle fields set to SOL N
84. ith the specified subject and the specified user set as the sender clone Object clone Returns a clone of this message containing a deep copy of its attachment getAttachment DataRow getAttachment Returns the attachment of this message Initially it is an empty DataRow but you can put any DataField into it and all the values will be converted to their corresponding ActionScript datatypes if you send the message to a client Message 137 ejep snwo si0 getSender String getSender Returns the name of the sender getSubject String getSubject Returns the subject of this message getUndeliveredCommand Command getUndeliveredCommand Returns the command that gets executed if the message can not be delivered to the recipient or null if none has been specified yet setUndeliveredCommand void setUndeliveredCommand Command com Sets the command that gets executed if the message can not be delivered to the recipi ent This is intended for messages that have a target on the server side N ote that the Command must be serializable if the O regano Server runs on more than one machine StringField extends DataField implements Cloneable Serializable The class corresponding to String objects in ActionScript Constructor Summary StringField String name String value Method Summary String getString void setString String newValue StringField StringField String
85. ition Can be referred to in the definitionID attribute in a userProp OF groupProp node lt column gt Contains one required attribute and one or more column child nodes Example lt column name age type int a o El oq c y fag o 5 name The name of the column type The datatype of the property See the type attribute of the groupProp node for a list of valid values The only restriction is that you can not use the counter type in a table definition lt log gt Contains one required attribute and 12 child nodes Example lt log output database gt lt login level warn gt lt logout level warn gt lt database level warn gt lt messaging level error gt lt groups level warn gt lt changeGroups level warn gt lt services level warn gt lt admin level info gt lt rmi level warn gt lt client_omus level info gt lt client_dev level warn gt lt extensions level warn gt lt log gt lt log gt 37 output One of the following two values database all log entries are written to the logging table in the database file all log entries are written to log txt Most useful for debugging You can set a log level for each of the 12 categories Valid values for the level attribute in each node are debug info warn and error The debug and info levels are useful for debugging but way to verbose if many users are logged in In this
86. ity gt lt in name phone gt lt in name userID gt lt statement gt UPDATE address SET street city phone WHERE userID lt statement gt lt dbWriter gt You can write Java code to execute those statements as follows DbTransaction ta new org omus DbTransaction ta add new org omus DbReader readUserID ta add new org omus DbWriter updateAddress address ta setParam new StringField username Thomas ta setParam new StringField street 217 Mulholland Drive ta setParam new StringField city Los Angeles ta setParam new StringField phone 27 27 55 55 DbResult res null try res ta execute int afRows res getAffectedRows address should be 1 catch DbException dbe handle Exception o S oa o 3 S y a Ss DbTransaction 143 Please note that the second statement has 4 lt in gt nodes Three of them street city and phone will be set by your Java code The last one userlD will be set automatically because it is configured as an lt out gt value in the first statement which will be available to all subsequent statements The attribute minR ows is set to 1 in the first statement so that execution of the transaction will be aborted if the result is empty because the second statement would fail anyway if no user with the specified name exists Constructor Summary DbTransaction Method Summary void add DbTransact
87. ked after a user has joined the group You can use the DataRow object which is empty initially to send additional data to the client which will be received in the param eter of the onChange event handler of the group object in the client if you develop an extension to the login group the additional data will be receceived in the onLogin or onRegister events userLeft void userLeft User user Invoked after a user has left the group You can still change the properties of the user This method gets invoked before the userJoined method of the new group will be invoked KeyGenerator Interface A key generated by a class that implements this interface can be used to encode pass words on the client This extension must be used together with a PasswordD ecoder extension Furthermore the corresponding encoding function must be written in KeyGenerator 99 xa snwo 310 ActionScript and set with the setPasswordEncoder method in org omus session in the client The generated key will be passed to the encoding method in the client and to the decoding method on the server You must specify the name of the class that implements this interface in the lt exten sions gt node in config xml Method Summary String generateKey generateKey String generateKey Invoked before a client will be requested to send the username and password this method must return a key that will be passed to the encoding method in the clie
88. l M ySQL to use that new database USE anyName Execute the SQL batch file with the command SOURCE path to oregano oregano sql If you want to use the Flash Admin Client you have to insert at least one administra tor into the admin table You can do this with the following SQL statement INSERT INTO admins VALUES 1 userID password mail home com 9 NOW NOW 1 Editing config xml This is the main configuration file for the O regano Server It is included in the config directory inside the server runtime directory You can leave most of the settings unchanged as the default values provided in the downloaded file will be sufficient to boot the server You can edit them later when you start developing your first applica tion There are only a few entries that you have to edit before you can successfully boot the server Edit the address attribute of the server node inside the serverConfig node The address can be an IP address or the human readable name ie www myserver com Edit the following four attributes in the database node url The URL of the database The format of the URL is specific to the JDBC implementa tion of your database For M ySQL it looks like this jdbc mysql localhost anyName auto reconnect true This URL says to use the mysql driver to connect to the database anyName On local host For MySQL make sure to include the auto reconnect flag so that the O regano connection pool does not have to cop
89. l send Mailbox load Mailbox removeAll Messenger sendToServer parsing incoming messages PropertyLoader loadGroup PropertyLoader loadUser PropertySet load PropertySet loadAll PropertySet synchronize Possible error codes dbe 001 dbe 002 dbe 006 dbe 007 bud 001 bud 003 dbe 001 dbe 002 dbe o001 dbe 002 bud 002 dbe 001 dbe 002 dbe o01 dbe 002 dbe 003 dbe 004 dbe 005 dbe 009 dbe o10 dbe on dbe o12 dbe 013 dbe 014 dbe 001 dbe 002 cgr 001 cgr 002 Cgr 003 Cgr 004 Cgr 005 grp oo1 grp oo1 grp 003 dbe o01 dbe 002 dbe o01 dbe 002 mbx 002 dbe o01 dbe 002 dbe o001 dbe 002 dbe 006 dbe 007 mbx 001 dbe o01 dbe 002 dbe o001 dbe 002 msg 003 msg 001 msg 002 dbe o01 dbe 002 dbe 008 prp 001 dbe o01 dbe 002 dbe 007 prp 001 dbe 001 dbe 002 prp 001 prp 004 dbe 001 dbe 002 prp 004 dbe 001 dbe 002 prp 002 prp 003 prp 004 Error codes 93 a s gt ar Session login dbe 001 dbe 002 ses 002 Ses 003 Ses 004 S S 005 ses 006 ses 008 ses 011 Ses 012 Session register dbe 001 dbe 002 ses 002 Ses 003 Ses 004 Ses 005 Ses 007 ses 008 ses 009 Ses 010 Ses 012 User setEmail dbe 001 dbe 002 usr 001 User setPassword dbe 001 dbe 002 usr 002 User setPermissions dbe 001 dbe 002 usr 003 usr 004 In addition each onError event can contain the error code ses 001 94 Error codes CHAPTER 6 Server API Writing server side extensions The
90. ld by this client release void release String lockName Releases the lock with the specified name releaseAll void releaseAll Releases all locks removeListener void removeListener Object listener Removes the specified listener from this object onAcquire onAcquire String lockName boolean success Event handler invoked when the acquisition of alock was accepted or rejected depend ing on the value of the second argument The lock can only be acquired if no other user currently holds the same lock onError onError Error error Event handler invoked when an error occured that was caused by one of the methods of the Locks object onRelease onRelease String lockName Event handler invoked when a lock was released onReleaseAll onReleaseAll Event handler invoked when all locks were released 60 Locks Log The log object contains methods to create custom log entries in the logging table on the server The object uses four different log levels DEBUG INFO WARN and ERROR A log level is an indication of the importance of a message Depending on the mininum log level you specified for the lt oregano dev gt node in the logging section in config xml a log entry might be ignored or sent to server If the configuration looks like this lt client_dev level warn gt all log entries of level WARN or higher will be sent to the server Accordingly calling org o
91. lone Object clone Returns a deep clone of the table getDefinition TableDefinition getDefinition Returns the TableDefinition object used in this table DataTable 131 e ep snwo si0 getRow DataRow getRow int index Returns the row at the specified position iterator Iterator iterator Returns an iterator over the rows of this table removeAllRows void removeAllRows Removes all rows from this table removeRow DataRow removeRow int index Removes and returns the row at the specified index size int size Returns the number of rows of this table sort void sort DataTable Comparator tableComp Sorts the table according to the order induced by the specified comparator DataTable Comparator Interface DataTable Comparators can be passed to the sort method of DataTable to allow pre cise control over the sort order Method Summary int compare DataRow r1 DataRow r2 132 DataTable Comparator compare int compare DataRow r1 DataRow r2 Compares its two arguments for order Returns a negative integer zero or a positive integer as the first argument is less than equal to or greater than the second DateField extends DataField implements Cloneable Serializable The class corresponding to Date objects in ActionScript Constructor Summary DateField String name Date value Method Summary Date getDate void
92. ly if they need to access it The value will be loaded into the PropertySet object of the Group object in the server Furthermore it will be loaded automatically into all the clients of the group With this setting you have quick access to the value in server extensions and in all clients Of course any changes will be reflected in all clients immedi ately Contains four required attributes two optional attributes and no child nodes Example lt userProp name age type int persistence writeOnChange cacheLevel off default 99 gt name The name of the property type The datatype of the property See the type attribute of the groupProp node for a list of valid values persistence M ust be one of the following values off writeOnLogout writeOnChange The value will not be stored in the database Each time the user logs in the value of this property will be reset to the default value The value will be stored in the database Any modifications will be written to the database when the user logs out Useful for values that change frequent ly The value will be stored in the database Each modification will be written to the database immediately lt userProp gt 35 la El oq c y fag o 5 The fields required to store the properties will be created automatically in the tables userprops or groupprops respectively On the other hand if you remove a property from the configuratio
93. me any newValue Sets the value of the property with the specified name to the specified new value The type of the new value must match the type you specified for this property in config xml Please note that the new values will not be written to the database and not be reflected in other clients before you commit all changes with a call to PropertySet synchronize size int size Returns the number of properties in this set synchronize void synchronize Synchronizes all modified properties in this set according to the synchronization settings in the XM L configuration file on the server This may include writing the new values to the database or updating them in other clients of the current group depending on the configuration onError onError PropertySet subset Error error Event handler invoked when an error occured The first argument is a PropertySet object that contains only the affected properties that could not be loaded or synchro nized depending on the method that caused the error onLoad onLoad PropertySet subset Event handler invoked when one or more properties were loaded The argument is a PropertySet object that contains only the affected properties onSynchronize onSynchronize PropertySet subset boolean clientRequest Event handler invoked when one or more properties were synchronized The first argument is a PropertySet object that contains only the affected properties T
94. me of the class to be used to decode passwords This attribute is optional The specified class must implement org omus ext PasswordDecoder and must always be used in conjunction with a key generator See the section on PasswordDecoder in the Server API chapter loginExtension The name of the class to be used to extend the login functionality This attribute is optional The specified class must implement org omus ext LoginExtension See the section on LoginExtension in the Server API chapter logoutExtension The name of the class to be used to extend the logout functionality This attribute is optional The specified class must implement org omus ext LogoutExtension Seethe section on LoginExtension in the Server API chapter lt admin gt Contains one required attribute three optional attributes and no child nodes If you do not want to use the Flash admin client for security concerns set enableClient to false and omit the remaining attributes N ote that in Version 1 0 0 there is no alternative If you want to logout a user or shutdown the server without loss of data you have to use the Flash admin client Later versions will come with a command line tool that has the same functionality and can be executed on the server Example lt admin enableClient true versionID myx5 2b keyGenerator AdminKey passwordDecoder AdminDecoder gt enableClient Boolean value Set this attribute to true if you want to use the Flash
95. message var attach msg getAttachment attach chatText _root getInputFieldContentSomehow org omus messenger sendToGroup msg Cunstructor Summary new org omus Message String subject Method Summary Object getAttachment String getSender String getSubject new new org omus Message String subject Constructs a new M essage object with the specified subject getAttachment Object getAttachment Returns the attachment of this M essage object It is a plain ActionScript object that is empty in a newly created M essage object You can add properties with one of the fol lowing datatypes boolean number String Date Array Object org omus Table getSender String getSender Returns the sender of this M essage object getSubject String getSubject Returns the subject of this M essage object 70 Message MessageFilter If you want fine grained control of which objects handle which kind of incoming mes sages you can register a M essageFilter object with the messenger object You can add an unlimited number of subjects and an unlimited number of listeners to each M essageFilter When a message is received that has a subject that was added to a M essageFilter object all the registered listeners in that M essageFilter receive an onMessage event In this example a filter is created that handles all messages with the subject start game or stop game var obj new Objec
96. method is an instance of the Buddies object because it shares the same interface with the buddylist See the sec tion on the Buddies object for details a 5 taa gt ar getBuddies Buddies getBuddies R eturns the Buddies object for this user See the section on the Buddies object for details getEmail String getEmail Returns the email address of the user getinBox Mailbox getInBox Returns the Mailbox object representing the in box See the section on the M ailbox object for details getLocks Locks getLocks Returns the Locks object for this user See the section on the Locks object for details User 89 getName String getName Returns the name of the user getOutBox Mailbox getOutBox Returns the M ailbox object representing the out box See the section on the M ailbox object for details getPassword String getPassword Returns the password of the user getPermissions int getPermissions Returns the permissions of the user a number between 0 and 10 o user has been deleted 1 user has been banned 2 8 user has normal status 9 10 user has administrator status The values between 2 and 8 make no difference to the Oregano Server You can use them for your application logic A newly registered user has a permission value set to 3 A user who has administrator status will not be logged out if you switch the server to debug mode using the Fla
97. ml file The value can be one of the following datatypes boolean number string Date Array Object org omus Table DbReader 47 a E 5 gt a DbResult This object represents the result of a transaction It will be passed to the onResult event handler of the DbTransaction object Method Summary int getAffectedRows String result D Table getTable String resultID getAffectedRows int getAffectedRows String resultID Returns the number of affected rows of the statement with the specified resultID The resultID must match the ID that you passed as the second argument to the constructor of the corresponding DbWriter object getTable org omus Table getTable String resultID Returns a reference to a table object The resultID must match the ID that you passed as the second argument to the constructor of the corresponding D bR eader object DbTransaction This object can be used to read and write to and from the database N ote that persistent properties will be written to the database automatically You only need this object if you created additional tables in the database This object is useful if you want to execute custom SQL statements For security rea sons you cannot construct those statements in the client Instead you must configure them in the dbCustom xml file on the server This approach may seem a bit cumber some at first sight But it is very versatile once you get used to it The followin
98. mparator ooooocccocccocccccccnnccccrr o 132 DaterField 00 A PS GG OS ia pio 133 DoubleField ocn cara 133 Field Listener iii a A Ble aS 134 Field Visitor E e E 135 INtRield oia aa Gee Ne ROLES Bee ee a ewes 135 HONS PICMG ct Ss wince asoness wee ida 136 Messagen A do ios 137 StingField sss cee otter A eg ea E EEEE E edie wie 138 TableDefinition 0 cece eee ec eee nent eee enes 139 Package Org OMUS db ccc cece cee e eee e eee eens 141 DDEXCeptiON mai Peal ited tose aia ees 141 DDR ade tii tee a Seated dias 141 DDRES Ute see so E siete eae eh PGRN PERE M SHE EE OR EE ER WS 142 PbTransaction Seta hE ES A 143 DbTransactionPart ccc cc cece eee rr 145 DDWriter voor 44088 date ae mee Oh ETE 146 8 Table of Contents CHAPTER 1 Feature Overview Oregano Server is a Multiuser Server for Flash clients It is free and released as Open Source under the GN U Lesser General Public License LGPL Since it is written in pure Java it runs on many operating systems including Linux Windows or MacOSX It is useful for client server applications that require low latency such as real time chat systems or shared whiteboard applications that would be difficult to develop with tra ditional H TT P based solutions Groups and User Management Oregano Server comes with database driven user management and a versatile mecha nism for creating and configuring groups All the interaction takes placein groups You
99. mus log debug Or org omus log info will be ignored in this case The Log object is a singleton that will be created automatically when a user logs in It can be referenced with org omus log Method Summary void addListener Object listener void debug String errorCode String info boolean debugEnabled void error String errorCode String info boolean errorEnabled void info String errorCode String info boolean infoEnabled void removeListener Object listener void warn String errorCode String info boolean warnEnabled a E 5 gt a Event Summary onLog String log addListener void addListener Object listener Adds the specified object as a listener for the onLog event debug void debug String errorCode String info Creates a log entry with the specified error code and info string if the log object is con figured to process messages of level DEBUG or higher The error code will be automati cally prefixed with cld to avoid confusion with built in error codes Log 61 debugEnabled boolean debugEnabled Returns true if the log object is configured to sent log entries of level DEBUG or higher to the server error void error String errorCode String info Creates a log entry with the specified error code and info string if the log object is con figured to process messages of level ERROR The error code will be automatically pre fixed with cld to a
100. n gt lt groupProp gt lt properties gt 32 lt properties gt lt globalProperties gt Contains no attributes and an unlimited number of optional groupProp or userProp child nodes The group properties you define inside this node will be created for all groups If you want to add group properties for a particular set of groups define them in the properties node within the correspomding group node Example lt globalProperties lt userProp gt lt see userProp section gt lt userProp gt lt groupProp gt lt see groupProp section gt lt groupProp gt lt globalProperties gt lt groupProp gt a o 3 oa y o Contains four required attributes two optional attributes and no child nodes Example lt groupProp name itemList type largeTable persistence writeOnChange cacheLevel serverCache definitionID itemL gt name The name of the property definitionID Applies to properties with a type attribute set to table or largeTable only Refers to the id attribute of the corresponding tableDefinition node For each table property you must define the name and datatype for each column in the tableDefinition node default The default value of this property This attribute will be ignored for the container types array object table because they are always empty by default If you specify the default value for a date property it must be the number of millisec
101. n file the corresponding column will not be removed in the data base thus you do not risk losing data if you boot Oregano Server with the wrong con figuration file by mistake The logging table will include an entry with a list of all columns that are obsolete so that you can delete them manually cacheLevel M ust be one of the following values off The value will not be cached in the clients nor in the server It has to be read from the database each time it is accessed from client side or server side code with the load methods of the PropertySet object serverCache The value will be loaded into the PropertySet object of the corresponding User object in the server This way you have quick access to the value if you write a server extension that reads or modifies the value frequently The value will not be loaded into any client thus the client side PropertySet objects must load the value from the server side object if they need to access it synchronizeClient The value will be loaded into the PropertySet object of the corresponding User object in the server Furthermore it will be loaded automatically into the client that the property is associated with With this setting you have quick access to the value in server extensions and in the client that owns this property Other clients in the group still have to explicitly load the value synchronizeGroup The value will be loaded into the PropertySet object of the corresponding User objec
102. nLoad PropertySet subset onSynchronize PropertySet subset boolean clientRequest addListener void addListener Object listener Adds the specified object as a listener for all the events the PropertySet object can gen erate contains boolean contains String propName Returns true if this PropertySet object contains a property with the specified name getOwner String Group getOwner Returns the owner of this PropertySet object If this object is associated with a user the name of the user will be returned asa string If it is associated with a group a reference to the group object will be returned getParent ProperySet getParent Returns the parent object of this PropertySet or null if there is no parent The PropertySet objects that get passed to the onSynchronize Or onLoad event handlers are only subsets of the original PropertySet objects containing only those properties that were affected by the synchronize or load operation In these cases you can use this method to obtain the parent object which contains all properties getPrimaryKey int getPrimaryKey Returns the primary key for this PropertySet object corresponding to the usrID and grpID fields in the userprops and groupprops tables in the database getType String getType String propName Returns the datatype of the property with the specified name 78 PropertySet getValue any getValue String propName Ret
103. name String value Creates a new StringField with the specified name and value 138 StringField getString String getString Returns the value of this StringField setString void setString String newValue Sets the value of this StringField to the specified string TableDefinition implements Cloneable Serializable TableD efinition objects are used to define the names and datatypes of the columns of a DataTable object Constructor Summary TableDefinition Method Summary void addColumn String name Class type Object clone boolean equals Object o int getColumnCount String getColumnName int index String getColumnNames Class getColumnType int index boolean matches DataRow row TableDefinition TableDefinition Creates a new table definition addColumn void addColumn String name Class type Adds a new column to this table definition This method will fail if this TableD efinition object was already used to construct a new DataTable object since it is unmodifiable after that The second argument must be one of the 10 subclasses of DataField TableDefinition 139 ejep snwo si0 clone Object clone Returns a clone of this table definition equals boolean equals Object o Returns true if the specified object is a table definition with the same sequence of columns getColumnCount int getColumnCount Returns the numb
104. names and datatypes of the columns of a Table object Constructor Summary new org omus TableDefinition Method Summary void addColumn String name String type int getColumnCount String getColumnName int index Array String getColumnNames String getColumnType int index boolean matches Object row a E 5 gt a TableDefinition new org omus TableDefinition Creates a new empty TableDefinition object addColumn void addColumn String name String type Adds a new column to this table definition This method will fail if this TableD efinition object was already used to construct a new org omus Table object The second argu ment must be one of the following strings boolean int long float string date array object table getColumnCount int getColumnCount Returns the number of columns in this table definition TableDefinition 87 getColumnName String getColumnName int index Returns the name of the column at the specified index position getColumnNames Array String getColumnNames Returns an array of all column names in the order they were added to this TableD efinition getColumnType String getColumnType int index Returns the datatype of the column at the specified index position matches boolean matches Object row Returns true if the specified object matches this table definition The number of prop erties of the speci
105. nfo string and the stackTrace of the specified Exception if the LogM anager is configured to process messages of level WARN or higher The error code will be automatically prefixed with ext to avoid confusion with built in error codes warnEnabled boolean warnEnabled Returns true if the LogM anager is configured to process log entries of level WARN or higher LogManager 111 o Q oa o 3 S wv a O 2 5 MessagingManager Handles the delivery of messages The M essagingM anager is intended for messages aimed at targets outside the current group For messages that you want to send to clients within the current group use sentToClients in Group or sendToClient in User instead The M essagingM anager is similar to the ActionScript M essenger object in the Client API Method Summary void publish Message msg void sendToAll Message msg void sendToGroup Message msg String groupName void sendToUser Message msg String recipient void subscribe User user String subject void unsubscribe User user String subject void unsubscribeAll User user publish void publish Message msg Sends a message to all users that have subscribed to the subject of this message It will be passed to the messageToUser method in org omus ext GroupExtension for all the recipients and then forwarded to the clients and received in the onMessage event hand ler in the client side M essenger object sendToAll void sendTo
106. ng errorCode DbException DbException String errorCode Creates a new DbException with the specified error code DbReader extends DbTransactionPart implements Serializable Represents a SELECT statement to be executed on the server Constructor Summary DbReader String configlD DbReader String configlD String resultID DbReader DbReader String configID Creates a new DbReader object The specified configlD must match a configlD attri bute in a lt dbReader gt node in dbCustom xml DbReader 141 qp snuo 310 DbReader DbReader String configID String resultID Creates anew DbReader object The specified configlD must match a configlD attri bute in a lt dbReader gt nodein dbCustom xml The specified resultID can be used to read values from the DbResult object DbResult implements Serializable Represents the result of a transaction Method Summary int getAffectedRows String result D Message getMessage String subject DataTable getTable String resultID getAffectedRows int getAffectedRows String resultID Returns the number of affected rows of the statement with the specified resultID The resultID must match the ID that you passed as the second argument to the constructor of the corresponding DbWriter object getMessage Message getMessage String subject Returns a message with the specified subject and the content of this D bR esult object as an attachment A con
107. nt and to the decoding method on the server LoginExtension Interface This interface is useful if you want to modify the way users are registered or logged in You must specify the name of the class that implements this interface in the lt exten sions gt node in config xml Method Summary void finishLogin User user void finishRegister User user boolean prepareLogin AuthenticationData data boolean prepareRegister RegistrationData data finishLogin void finishLogin User user Invoked after the user has been logged in finishRegister void finishRegister User user Invoked after the user has been registered If the password for the new user was gener ated by this LoginExtension this is the right place to send an email to the new user con taining a registration confirmation and her password 100 LoginExtension prepareLogin boolean prepareLogin AuthenticationData data InetAddess clientAddress int clientPort Invoked before a registered user is logged in The AuthenticationD ata object contains methods to read or set the name and password of the user If this method returns false the login will be aborted This way you can implement some kind of error checking on the server or load some additional data before the user will be logged in You can even use this method to authenticate the user with a different server application if Oregano Server is tied to a legacy system You can use the setErro
108. ntry with the specified error code info string and the stackTrace of the specified Exception if the LogM anager is configured to process messages of level LogManager 109 o Q oa o 3 S wv a O 2 5 ERROR The error code will be automatically prefixed with ext to avoid confusion with built in error codes errorEnabled boolean errorEnabled Returns true if the LogM anager is configured to process log entries of level ERROR or higher info void info String errorCode Creates a log entry with the specified error code if the LogM anager is configured to process messages of level INFO or higher The error code will be automatically prefixed with ext to avoid confusion with built in error codes info void info String errorCode String info Creates a log entry with the specified error code and info string if the LogM anager is configured to process messages of level INFO or higher The error code will be auto matically prefixed with ext to avoid confusion with built in error codes info void info String errorCode Exception e Creates a log entry with the specified error code and the stackTrace of the specified Exception if the LogM anager is configured to process messages of level INFO or high er The error code will be automatically prefixed with ext to avoid confusion with built in error codes info void info String errorCode Exception e String info Creates a log e
109. ntry with the specified error code info string and the stackTrace of the specified Exception if the LogM anager is configured to process messages of level INFO or higher The error code will be automatically prefixed with ext to avoid confusion with built in error codes infoEnabled boolean infoEnabled Returns true if the LogM anager is configured to process log entries of level INFO or higher 110 LogManager warn void warn String errorCode Creates a log entry with the specified error code if the LogM anager is configured to process messages of level WARN or higher The error code will be automatically prefixed with ext to avoid confusion with built in error codes warn void warn String errorCode String info Creates a log entry with the specified error code and info string if the LogM anager is configured to process messages of level WARN or higher The error code will be auto matically prefixed with ext to avoid confusion with built in error codes warn void warn String errorCode Exception e Creates a log entry with the specified error code and the stackTrace of the specified Exception if the LogM anager is configured to process messages of level WARN or higher The error code will be automatically prefixed with ext to avoid confusion with built in error codes warn void warn String errorCode Exception e String info Creates a log entry with the specified error code i
110. object matches the table definition See the entry for TableDefinition match for details getDefinition TableDefinition getDefinition Returns the TableD efinition object for this table getRow Object getRow int index Returns the row at the specified index position removeAllRows n E 5 gt a void removeAllRows Removes all rows from this table object removeListener void removeListener Object listener Removes the specified listener from this object removeRow Object removeRow int index Removes and returns the row at the specified index position size int size Returns the number of rows of this table Table 85 sort void sort Function sortFunc Sorts the table using the specified comparison function Given two arguments row1 and row2 the function should return the following values 1 if row1 should appear before row2 o if row1 row2 1 if row1 should appear after row2 sortBy void sortBy String column boolean ascending Sorts the table by the column with the specified name updateRow void updateRow int index Object row Updates the row at the specified index position This method will only succeed if the specified row object matches the table definition See the entry for TableDefinition match for details onAddRow onAddRow Table table Object row boolean clientRequest Event handler invoked when a new ro
111. of affected rows in the DbResult object DbWriter 51 setParam void setParam String name any value Sets the parameter with the specified name to the specified value The name of the parameter must match the name attribute of one of the lt in gt nodes you specified in the dbCustom file The value can be one of the following datatypes boolean number string Date Array Object org omus Table Error An error object gets passed to all the onError event handlers You can use it to retrieve detailed information about the error Method Summary Array getArguments String getCode String getDescription String getMethodName getArguments Array getArguments Returns an array of all the arguments that were passed to the method that caused the error M ay return null if the error was caused by the server getCode String getCode Returns the error code of that object getDescription String getDescription Returns a description of the error that occured getMethodName String getMethodName Returns the name of the method that caused the error M ay return nul1 if the error was caused by the server 52 Error Group The group object represents the group that the client is currently member of Each client can only be member of one group at any point in time The methods of the group object can be used to obtain information about the current group and to retrieve the Propert
112. of the login group You do not receive onUserJoined events in the client if another user logs in and you do not have access to the properties of other users in the login group All these lim itations were implemented to avoid bottlenecks in the login process The actual inter action should take place in one of the other groups Example lt loginGroup extension LoginExt gt lt properties gt lt see properties section gt lt properties gt lt loginGroup gt a o El oq c y fag o 5 extension The name of the class to be used to extend the functionality of the login group This attri bute is optional The specified class must implement org omus ext GroupExtension See the section on GroupExtension in the Server API chapter lt group gt Contains two required attributes one optional attribute an unlimited number of optional startup child nodes and an optional properties child node Example lt group configID publicRoom userLimit 25 extension PublicExt gt lt startup server serv1 name room_1 gt lt startup server serv1 name room_2 gt lt startup server serv1 name room_3 gt lt properties gt lt see properties section gt lt properties gt lt group gt configID An arbitrary string The configlD can be passed to the change method of the Group object in the client to specify which configuration to use to create the new group lt group gt 31 u
113. on address is either the human readable name of your server like www myServer com or the IP address If Oregano Server runs on more than one machine only the address of the Primary Server must be specified in the init method the other servers will be found automatically loginPort and reconnectPort must be 1024 or higher reconnectPort is optional it is only required if your server runs on more than one machine Session 81 a E 5 gt a isConnected boolean isConnected Returns true if it is possible to send a command to the server Returns false if the user is not logged in if she is already logged out or the connection is broken Furthermore it returns false if changing groups is in progress You cannot send messages to the server before the connection to the new group has been fully established login void login String username String password Used to login a user who is already registered with the server All possible errors like invalid passwords are passed to the onError event logout void logout Closes the connection to the server register void register String username String password String email Used to register a new user with the server All possible errors like duplicate user names are passed to the onError event removeListener void removeListener Object listener Removes the specified listener from this object setPasswordEncoder boolean setPas
114. onds from the epoch midnight GMT January 1st 1970 If you are not in the mood for calculating the value you can use the getTime method of a java util Date or the getTime method of an ActionScript Date object lt groupProp gt 33 type The datatype of the property M ust be one of the following values attribute value boolean int long float counter string largeString array 3 largeArray gt object 3 largeObject table 3 largeTable max 255 characters ActionScript datatype Java datatype boolean BooleanField number IntField number LongField number DoubleField number CounterField String StringField String StringField Array DataList Array DataList Object DataRow Object DataRow org omus Table DataTable org omus Table DataTable 2 limit depends on the internal datatype of your database that maps to JDBCs longvarchar 3 max 255 characters for the marshalled value For a description of the special Java datatypes used to map the corresponding ActionScript types see the section on package org omus data in the Server API chap ter persistence M ust be one of the following values off writeOnRemoval writeOnChange The value will not be stored in the database Each time the group is created the value of this property will be reset to the default value The value will be stored in the database Any modifications will be written to the database when the group is removed Dynamically
115. or developing Flash multiuser applications The Oregano Server Runtime and the O regano Client All other pieces are optional Download the O regano Server Runtime archive to your server machine and simply unzip it Before you can boot O regano Server you must create the required tables in your database and edit the start script and configuration file which will be explained in the next three sections The Oregano Client archive contains the ActionScript files required to be included with your Flash movies Unzip the archive and copy the whole oregano_as directory to the directory of your Flash files Read the introductory sections in the Client API chapter for further instructions The documentation for Oregano Server includes the User M anual you are reading right now and javadoc generated documentation in HTM L format The latter contains the same information as the Reference section of the Server API chapter in this manual The optional archives in the download section include the ava source code the simple example application which is described in Chapter 3 and a small Flash admin client Creating the Oregano tables Before you boot Oregano Server for the first time the required tables must be created from the SQL batch file oregano sql in your Oregano server runtime directory For M ySQL the following steps are required 12 Installation Start the mysql command line tool Create a new database with CREATE DATABASE anyName Tel
116. orCode Returns the error code or null if none was specified yet 102 AuthenticationData getPassword String getPassword Returns the password of the user getUsername String getUsername Returns the name of the user setErrorCode void setErrorCode String newCode Sets the error code to the specified string The code will be prefixed with cld auto matically to avoid confusion with built in error codes It will be sent to the client if the prepareLogin method in org omus ext LoginExtension returns false so that the login will be aborted setPassword void setPassword String newPassword Sets the password of the user to the specified string setUsername void setUsername String newName Sets the name of the user to the specified string Command Interface An interface for commands that will be passed to one of the methods in TaskM anager to addCommand in Group or to setUndeliveredCommand in M essage Method Summary void execute execute void execute Executes the command Command 103 xa snwo 3s10 Group Represents a group of users For each group that will be created due to an entry in con fig xml or dynamically by a client an instance of Group will be created The only way to obtain a reference to a Group instance is the groupCreated method in org omus ext GroupExtension The Java Group class is similar to the ActionScript Group object in th
117. ou use a database that is not capable of handling transactions like the M yISAM default table type of MySQL lt database gt 27 lt typeMap gt Contains no attributes and seven child nodes Each database may have its own mapping of JDBC datatypes to their internal datatypes For M ySQL the typeM ap node looks as follows lt tinyint dbType TINYINT gt lt integer dbType INTEGER gt lt bigint dbType BIGINT gt lt double dbType DOUBLE gt lt timestamp dbType DATETIME gt lt varchar dbType VARCHAR 255 gt lt longvarchar dbType TEXT gt The names of the nodes are the seven DBC datatypes used by the O regano Server The dbType attribute specifies the corresponding MySQL datatype that will be used in CREATE TABLE statements The datatype mappings will be verified when the server boots If a mismatch is detected an error description will be written to bootLog txt and the booting will be aborted If you manage to create a working type map for other databases than M ySQ L feel free to send it to info oregano server org lt statistics gt Contains one required attribute and no child nodes Example lt statistics periodStart 00 00 gt periodStart The time when the server should switch to the next date for all the statistical recordings it creates The time must be specified in the format hh mm 00 00 is the most obvi ous value but we tend to use 04 00 in our projects because at 4 00 most peo
118. perties A reference to its avatar M ovieClip and the PropertySet object that belongs to the user This is the constructor AvatarObj function propSet dp this propSet propSet this propSet addListener this var username propSet getOwner _root main attachMovie Avatar username dp this mc _root main username this mc gotoAndStop propSet getValue avatar this changePos J The avatar clip is attached to the main clip in _root After that the new clip is sent to the frame that contains the avatar graphics the user had chosen and finally this changePos is called to move the clip to the right position In the second line of the constructor the object registers itself as a listener with the PropertySet object It handles the onSynchronize event that occurs when a property value has changed Since there are only two properties and the avatar property is never changed it looks for a property named position and moves the avatar to the corre sponding position Avatar0bj prototype onSynchronize function propSet if propSet contains position this changePos AvatarObj prototype changePos function var pos this propSet getValue position this mc x pos x this mc y pos y 20 Example Application Chat The chat object is included in chat as It is really simple It was registered as a listener with the messenger object in the init method of the login object It listens for incom
119. ple are asleep This way a login at 23 00 will be added to the same record as a login at 01 00 which we felt is the best way to detect nights with many visitors The statistical recordings that O regano Server creates include the number of logins per day the number of new registrations per day the maximum number of concurrent con nections per day and the average login time per user per day It will be written to the statistics table in the database In addition the same time specified in this attribute will be used for the executeDaily executeWeekly and executeMonthly methods of the server side TaskM anager class 28 lt statistics gt lt services gt Contains six required attributes and no child nodes Example lt services mailboxLimit 200 buddyLimit 100 blacklistLimit 100 groupListCache 30 groupListInterval 60 userListCache 30 userListInterval 60 ES mailboxLimit The maximum number of mails in the in box for each user buddyLimit a El oq c y fag o 5 The maximum number of buddies each user can put into his buddylist blacklistLimit The maximum number of users each user can put into his blacklist groupListCache The number of seconds the list of groups will be cached You can load the list with the loadGroupList method in the Info object of the client If you enable caching the server will cache the message containing the list of groups for subsequent requests until th
120. rCode method of the AuthenticationD ata object to send customized error codes to the clients Otherwise a default error code will be sent prepareRegister boolean prepareRegister RegistrationData data InetAddess clientAddress int clientPort Invoked before a new user is registered The RegistrationD ata object contains methods to read or set the name password or email address of the user If this method returns false the registration will be aborted This way you can implement some kind of error checking on the server or load some additional data before the user will be registered It is a good idea to generate the password on the server and not to use the one sent from the client You can use the finishRegister method of this extension to send the gen erated password in an email to the new user and thus verify the email address that she entered To send customized error codes to the clients you can use the setErrorCode method of the AuthenticationD ata object O therwise a default error code will be sent LogoutExtension Interface A logout extension can be written to modify the properties of the user before they are written to the database You must specify the name of the class that implements this interface in the lt extensions gt node in config xml Method Summary void prepareLogout User user prepareLogout void prepareLogout User user Invoked when the specified user will be logged out You can still modify th
121. roperties The PropertySet class is similar to the ActionScript PropertySet object in the Client API Each group and each user have a set of properties associated with them The datatype as well as persistence and synchronization settings for each property must be defined in the XM L configuration file on the server See the Configuration chapter for details The PropertySet object can be used to read individ ual property values to load properties from the database or to synchronize them The actual modification of the value of a property is carried out through methods of the DataField instance that represents the property Please note that modified values will not be written to the database and not be reflected in the clients before you commit all changes with a call to synchronize Example code to change some properties of a user and synchronize them might look as follows PropertySet ps group getProperties IntField age IntField ps getValue age age setInt 27 BooleanField married BooleanField ps getValue married married setBoolean false try ps synchronize catch org omus db DbException dbe System out println ERROR dbe o Q ga o 3 S wv a O 2 5 PropertySet 113 Method Summary boolean contains String name O bject getOwner IntField getPrimaryKey Class getType String name DataField getValue String name boolean isLoaded String name boolean isModified String name
122. se onClose Event handler invoked when the group was closed so that no other user can join onChange onChange Object data Event handler invoked when the attempt to change groups succeeded When this event handler is invoked the group object already represents the new group The argument is an empty object unless you wrote a GroupExtension as a server side plugin which can be used to send additional data to the client onError onError Error error Event handler invoked when an error occured that was caused by one of the following methods of the Group object change open close onUserJoined onUserJoined PropertySet userProps Event handler invoked when a user joined this group The argument is the PropertySet object that represents the new user onUserLeft onUserLeft PropertySet userProps Event handler invoked when a user left this group The argument is the PropertySet object that represents the user that has left the group onOpen onOpen Event handler invoked when the group was opened so that other users can join Info Basically a small collection of methods to retrieve information that did not fit into any other object The Info object is a singleton that will be created automatically when a user logs in It can be referenced with org omus info 56 Info Method Summary void addListener Object listener void findUser String username void loadGroupList vo
123. serLimit The maximum number of users permitted to join the group extension The name of the class to be used to extend the functionality of all groups that were cre ated with the id specified in the configlD attribute This attribute is optional The spec ified class must implement org omus ext GroupExtension See the section on GroupExtension in the Server API chapter lt startup gt Contains two required attributes and no child nodes Each group node can contain an unlimited number of startup nodes With each startup node you define a group that will be created when the server boots Example lt startup server serv1 name room_1 gt server TheID of the server that this group should be created on Refers to an ID that you spec ified in the corresponding server node name The name of the group You can create an unlimited number of groups with the same configlD but different names but you cannot create two groups with the same name lt properties gt Contains no attributes and an unlimited number of optional groupProp child nodes Each group node can contain a properties node to define properties for groups creat ed with a particular configlD In addition there is a top level globalProperties node in config xml to define properties for all groups and for users Example lt properties lt groupProp gt lt see groupProp section gt lt groupProp gt lt groupProp gt lt see groupProp sectio
124. sh Admin Client getProperties PropertySet getProperties Returns the PropertySet object associated with this user removeListener void removeListener Object listener Removes the specified listener from this object go User setEmail void setEmail String newEmail Sets the email address for this user You must set the permissions for this method in con fig xml on the server See the Configuration chapter for details This method may fail if the server is configured with emailUnique true and a user with the same email address is already registered setPassword void setPassword String newPassword Sets the password for this user You must set the permissions for this method in con fig xml on the server See the Configuration chapter for details setPermissions void setPermissions int newPermissions Sets the password for this user You must set the permissions for this method in con fig xml on the server See the Configuration chapter for details onError onError Error error Event handler invoked when an error occured that was caused by one of the following methods of the user object setEmail setPassword setPermissions onSetEmail onSetEmail Event handler invoked when the email address was modified and written to the data base onSetPassword onSetPassword Event handler invoked when the password was modified and written to the database onSetPerm
125. swordEncoder Function encoder Optionally a function can be specified that encodes the password used in the login and register methods It requires two arguments The first argument is the password the sec ond is a string key send by the server that you can use to encode the password The server then uses the same key for decoding The function must return the encoded pass word You have to write the corresponding server side decoder as a J ava extension See the section about the org omus ext package in the Server API chapter A very simple example function might look as follows pwdEncoder function password serverKey var offset parseInt serverKey var encoded for var i 0 i lt password length i var num password charCodeAt i offset 82 Session encoded num return encoded org omus session setPasswordEncoder pwdEncoder onError onError Error error Event handler invoked when an error occured The error might be caused by a call to the login or register methods which might have failed In addition the session object handles all the unknown errors which might be send by the server In this case error getMethod returns null onLogin onLogin Object data Event handler invoked when an attempt to login succeeded The argument is an empty object unless you wrote a LoginExtension as a server side plugin which can be used to send additional data to the client
126. t obj onMessage function msg var at msg getAttachment trace at newScore var filter new org omus MessageFilter filter addSubject start game filter addSubject stop game filter addListener obj org omus messenger addFilter filter If you combine M essageFilter objects with the publish subscribe mechanism in the M essenger object you get precise control over the way messages are distributed and processed Constructor Summary new org omus MessageFilter Method Summary void addListener Object listener void addSubject String subject void removeListener Object listener void removeSubject String subject new new org omus MessageFilter Constructs a new M essageFilter object with the specified subject addListener void addListener Object listener Adds the specified object as a listener to this M essageFilter The listener object will receive an onMessage event for all incoming messages that have a subject that was added to this filter with the addSubject method MessageFilter 71 a 5 gt a addSubject void addSubject String subject Adds the specified subject to this M essageFilter removeListener void removeListener Object listener Removes the specified listener from this object removeSubject void removeSubject String subject Removes the specified subject from this M essageF ilter Messenger The M essenger objec
127. t h Se ore a Ste 92 6 Server A ie eee tee 95 Writing server side extensions eee eee 95 Package overview cisircirii idas 96 Package Org OMUS eXt oooccccocccccccnnccccncn ccoo 96 GFOUPEXteNSION ici dias Reese ented eed tae Wes 96 KEVGENEF ATOR coi Gg seit octet oust oline aay ota 99 LOGINEXTONSION es joes close Coie eas eles ied diye ese BE Sale eas eee ee 100 LogoutExtensiony muta sabe aes Mee as 101 PasswordDecoder sce e cece eee rr 102 Package OFrg OMUS COMe cece eee cee e cece eens 102 AuthenticationData eee eee cee eens 102 GCOMMANG seeren eea E ches lowe Gels eee ee een eee 103 COUPE A eo Store aes aes 104 GroupCreationData 0 cece eee eee eee eee eee 106 Table of Contents 7 LOpMaNa Bers o create sens a arte BeAr A 107 MessagingManager 0 cc cece cece EEEIEE 112 PropertySet esse eye Rhee Res See eR A SE BE es 113 PropertyUpdate cece eee eee eee 116 RegistrationData 0 ccc cece cece eens 116 E NN 117 EI Sete Sedans ogee see a bee E 118 Us a a A A a Rca a Mest a atte 119 Package org omuS data ooooocccconcccccncccccn o 122 Boolean Field nc soii a dl a wee ns 122 CouniterBieldl a vasa es E Silene eee oa EA eed 123 DataPiel dss cscvesc cc te dicat peace rd Rawr ha PR ORS 124 DataliSt ica risa 125 DataList Comparator 2 0 ccc eee eee een teen ee 128 DataROW iia eee re A aa 128 DataTable curioso a rato 130 DataTable Co
128. t handles receiving sending and filtering of M essage objects which are different from M ail objects in that they are not persistent If the recipient is offline the message will be discarded There is a publish subscribe mechanism which you can use to easily control the distribution of messages The M essenger object is a singleton that will be created automatically when a user logs in It can be referenced with org omus messenger Method Summary void addListener Object listener void addFilter MessageFilter filter Array String getSubscriptions boolean isSubscribed String subject void publish Message msg void removeListener Object listener void removeFilter MessageFilter filter void sendToAll Message msg void sendToGroup Message msg String groupName void sendToServer Message msg void sendToUser Message msg String username boolean sameGroup void subscribe String subject void unsubscribe String subject void unsubscribeAll Event Summary onError Error error onMessage Message msg onSubscribe String subject onUnsubscribe String subject onUnsubscribeAll 72 Messenger addListener void addListener Object listener Adds the specified object as a listener for all events the M essenger object can generate addFilter void addFilter MessageFilter filter Adds a filter to the messenger object Filtering may be convenient if you want fine grained control of
129. t in the server Furthermore it will be loaded automatically into all the clients of the group With this setting you have quick access to the value in server extensions and in all clients definitionID Applies to properties with a type attribute set to table or largeTable only Refers to the id attribute of the corresponding tableDefinition node For each table property you must define the name and datatype for each column in the tableDefinition node default The default value of this property This attribute will be ignored for the container types array object table because they are always empty by default If you specify the default value for a date property it must be the number of milliseconds from the epoch midnight GMT January 1st 1970 If you are not in the mood for calculating the value you can use the getTime method of a java util Date or the getTime method of an ActionScript Date object lt tableDefinition gt Contains one required attribute and one or more column child nodes N eeded if you configured one or more properties of type table Each table definition can be used for more than one table property 36 lt tableDefinition gt Example lt tableDefinition id playerList gt lt column name name type string gt lt column name age type int gt lt column name score type int gt lt column name repository type array gt lt tableDefinition gt id The ID of this table defin
130. task for repeated fixed delay execution beginning after the spec ified delay For details see the documentation for the corresponding method in java util Timer o El ga o 3 S Nn a o 2 5 scheduleAtFixedRate void scheduleAtFixedRate TimerTask task Date firstTime long period Schedules the specified task for repeated fixed rate execution beginning at the specified time For details seethe documentation for the corresponding method in java util Timer TaskManager 119 scheduleAtFixedRate void scheduleAtFixedRate TimerTask task long delay long period Schedules the specified task for repeated fixed rate execution beginning after the spec ified delay For details see the documentation for the corresponding method in java util Timer User Represents a single user Method Summary String getEmail String getName String getPassword int getPermissions PropertySet getProperties void logout String errorCode void sendToClient Message msg getEmail String getEmail Returns the email address of the user getName String getName Returns the name of the user getPassword String getPassword Returns the password of the user getPermissions int getPermissions Returns the permissions of the user a number between 0 and 10 o user has been deleted 1 user has been banned 2 8 user has normal status 9 10 user has administrator status 120
131. that will be created dynamically due to a client calling org omus group change anyName spec false will load the same extension too po snuwo 310 Method Summary void finishGroupCreation Group group void groupRemoved void messageFromClient Message msg User sender boolean messageToGroup Message msg boolean messageToUser Message msg User recipient boolean prepareGroupCreation GroupCreationData gcd boolean syncGroupProperties PropertyUpdate newValues User sender boolean syncUserProperties PropertyUpdate newValues User sender User owner void userJoined User user DataRow extraData void userLeft User user GroupExtension 97 finishGroupCreation void finishGroupCreation Group group Invoked after the group has been created Each class that implements this interface should keep a reference to the group object in a field groupRemoved void groupRemoved Invoked after the group has been removed You can still modify the properties of this group which will be written to the database after this method finished executing messageFromClient void messageFromClient Message msg User sender Invoked after a message from the specified sender has been received This event origi nates from a client calling sendToServer in org omus messenger messageToGroup boolean messageToGroup Message msg Invoked before a message is sent to all the clients who are currently member of this
132. thod that caused the error EventModel 41 a E 5 gt a Exchanging data Building multiuser applications implies that data has to be exchanged between clients and the server There are two approaches to accomplish this in Oregano Server Using properties or using messages To give you an impression on the difference of these two approaches let s look at a small example In a visual chat application with an avatar representing each user you want to visual ize the movement of the avatars and exchange chat messages The former is best done using a property the latter is a typical job of a M essage object M essage objects are transient They can send data from one client to all the other clients to one particular client or to the server The other clients receive those messages in their onMessage event handler of the messenger object After the message was received the client and the server forget about it This suits well for the task of sending chat messages because they are only needed at the moment they are received If a new user enters the room later she might not be interested in reading all the stuff that was said hours ago The position of an avatar on the other hand must be sent to each other client includ ing those who join later This can be accomplished with a property The server keeps track of changes and if a new user enters a group the server sends the current values for all properties of the group and
133. tly mem ber of the group The array is sorted alphabetically by user names getConfiglD String getConfigID Returns the configlD of the group It identifies the corresponding lt group gt node in con fig xml that was used to configure this group You can create an unlimited number of groups with the same configlD but different names See the Configuration chapter for more details 54 Group getName String getName Returns the name of the group getProperties PropertySet getProperties Returns the PropertySet object associated with this group getUserCount int getUserCount Returns the number of users who are currently member of this group getUserLimit int getUserLimit Returns the maximum number of users permitted for this group getUserProperties n s gt a PropertySet getUserProperties String username Returns the PropertySet object associated with a user who is currently member of this group Returns nu11 if no user with the specified name exists in this group isClosed boolean isClosed Returns true if the group is closed so that no other users can join isFull boolean isFull Returns true if the maximum number of users has been reached removeListener void removeListener Object listener Removes the specified listener from this object open void open Opens the group for other users to join Group 55 onClo
134. to every DataField through its accept method Method Summary void visit BooleanField bf void visit CounterField cf void visit DataList dl void visit DataRow dr void visit DataTable dt void visit DateField df void visit DoubleField df void visit IntField inf void visit LongField If void visit StringField sf M ethod details are omitted each method visits the specified field IntField extends DataField implements Cloneable Serializable A class for properties or table columns configured as an int corresponding to the num ber datatype in ActionScript This type of DataField will only be created if a property or column in a table is explicitly configured as an int All other ActionScript numbers that are converted automatically will be converted to DoubleFields Constructor Summary IntField String name int value Method Summary int getint void setint int newValue IntField IntField String name int value Creates a new IntField with the specified name and value ejep snulo 310 IntField 135 getint int getInt Returns the value of this IntField as an int setint void setInt int newValue Sets the value of this IntField to the specified int LongField extends DataField implements Cloneable Serializable A class for properties or table columns configured as a long corresponding to the num ber datatype in ActionScript This type of DataField will onl
135. to every group that will be created on the server the latter is used if you write a local extension only intended for groups created with a particular configlD If you combine both approaches make sure that your local extension is a subclass of your defaultExtension otherwise the functionality of your defaultExtension would be wiped out by the methods in your local one Let s assume you develop a default extension with the following class body class MyGlobalExtension implements org omus ext GroupExtension In this case the groupC onfig node in config xml should look as follows lt groupConfig defaultExtension MyGlobalExtension If you want to add special behaviour to a particular set of groups you can define a sub class class MySpecialExtension extends MyGlobalExtension Each method in this subclass should call the method in the superclass that it overrides if you want to combine the functionality of your local and global extensions The node for the groups that are supposed to load this extension might look as follows lt group configID spec userLimit 50 extension MySpecialExtension gt lt startup server serv1 name spec_A gt lt startup server serv1 name spec_B gt lt group gt When the server boots two groups named spec A and spec_B will be created and both will load the extension class M ySpecialExtension which in turn is a subclass of M yGlobalExtension Furthermore each group
136. u must use the setParam method of those objects size int size Returns the number of DbWriter and DbReader objects that have been added to this transaction DbTransactionPart implements Serializable Abstract superclass of DbWriter and D bR eader Method Summary void setAllParams DataRow dr void setParam DataField df setAllParams void setAllParams DataRow dr Adds all DataFields contained in the specified DataRow as a parameter to this DbTransactionPart The name of each DataField must have a matching name attribute in one of the lt in gt nodes you specified in the dbCustom xml file setParam void setParam DataField df Adds the specified DataField as a parameter to this DbTransactionPart Thename of the DataField must match the name attribute of one of the lt in gt nodes you specified in the dbCustom xml file DbTransactionPart 145 o S ga o 3 S y a Ss DbWriter extends DbTransactionPart implements Serializable Represents a DELETE UPDATE Or INSERT statement to be executed on the server Constructor Summary DbWriter String configlD DbWriter String configlD String resultID DbWriter DbWriter String configID Creates anew DbWriter object The specified configlD must match a configlD attri bute in a lt dbWriter gt node in dbCustom xml DbWriter DbWriter String configID String resultID Creates anew DbWriter object The specified configlD must match
137. urns the value of the property with the specified name or nu11 if the property was not loaded yet isLoaded boolean isLoaded String propName Returns true if the value of the property with the specified name has been loaded into the client isModified boolean isModified String propName Returns true if the property with the specified name was modified since the last onSynchronize event isSynchronized boolean isSynchronized Returns true if no property was modified since the last onSynchronize event a 5 gt a isValid boolean isValid Returns true if this PropertySet object is associated with the current group or a user in the current group If you store a reference to a PropertySet object in a variable and the user that owns this PropertySet left the group the values of all properties in this set become stale because they will no longer be synchronized automatically load void load Array String propNames Loads all values of the properties with the specified names into the client Please note that the values of some properties will be loaded into the client automatically depend ing on their configuration loadAll void loadAll Loads the values of all properties that are not loaded automatically PropertySet 79 removeListener void removeListener Object listener Removes the specified listener from this object setValue void setValue String propNa
138. venient short cut if you want to send the values that you read from the database to a client getTable DataTable getTable String resultID Returns a table object read from the database The resultlD must match the ID that you passed as the second argument to the constructor of the corresponding DbReader object 142 DbResult DbTransaction implements Serializable Represents a transaction contains one or more DbWriter or DbReader objects to exe cute custom SQL statements The statements must be configured in the dbCustom xml file on the server This approach may seem a bit cumbersome at first sight But it is very versatile once you get used to it The following example illustrates how you can use the DbTransaction object to read a user ID from one table and use that ID to change a value in another table By the way It is the same example used to illustrate the use of the client side D bTransaction object M ost of the classes in org omus db have their twins in the Client API The corresponding entries in dbCustom xml might look as follows see the Configuration chapter for more details lt dbReader configID readUserID rollbackOnError true minRows 1 gt lt in name username gt lt out name userID gt lt statement gt SELECT userID FROM reginfo WHERE username lt statement gt lt dbReader gt lt dbWriter configID updateAddress rollbackOnError true gt lt in name street gt lt in name c
139. vent that two users start a drag operation concurrently you can use a lock for each draggable item on the screen Example code to set up a listener for the locks object might look as follows var locks org omus user getLocks var lis new Object 58 Locks lis onAcquire function lockName success if success if lockName draggableCircle start drag operation for circle else if lockName draggableSquare start drag operation for square else show error message or play sound E locks addListener lis Method Summary void acquire String lockName void addListener Object listener Array String getAllAcquired boolean isAcquired String lockName void release String lockName void releaseAll void removeListener Object listener a s gt 2 Event Summary onAcquire String lockName boolean success onError Error error onRelease String lockName onReleaseAll acquire void acquire String lockName Tries to acquire the lock with the specified name addListener void addListener Object listener Adds the specified object as a listener for all the events the Locks object can generate getAllAcquired Array String getAllAcquired Returns a list of all locks currently held by this client Locks 59 isAcquired boolean isAcquired String lockName Returns true if a lock with the specified name is currently he
140. ver runs on more than one machine This port num ber must be passed to the init method of the client side Session object admin The admin port A number between 1024 and 65535 This attribute is optional It must be specified if you enable the admin client see the section on the admin node for details The port number must be entered on the login screen in the Flash admin client rmi The RMI port A number between 1024 and 65535 This attribute is optional It must be specified if the Oregano Server runs on more than one machine N ote that this port does not have to be open to the public It will only be used to exchange data between server machines lt extensions gt Contains four optional attributes and no child nodes O regano Server is fully functional without any extensions so if the built in functionality is sufficient for your application you do not need to develop server side extensions Example lt extensions keyGenerator MyGenerator passwordDecoder MyDecoder loginExtension Validator logoutExtension Stats gt lt extensions gt 23 N 3 oq E y o keyGenerator The name of the class to be used to generate keys for password encryption This attri bute is optional The specified class must implement org omus ext KeyGenerator and must always be used in conjunction with a password decoder See the section on K eyGenerator in the Server API chapter passwordDecoder The na
141. void confusion with built in error codes errorEnabled boolean errorEnabled Returns true if the log object is configured to sent log entries of level ERROR to the server info void info String errorCode String info Creates a log entry with the specified error code and info string if the log object is con figured to process messages of level INFO or higher The error code will be automatical ly prefixed with cld to avoid confusion with built in error codes infoEnabled boolean infoEnabled Returns true if the log object is configured to sent log entries of level INFO or higher to the server removeListener void removeListener Object listener Removes the specified listener from this object warn void warn String errorCode String info Creates a log entry with the specified error code and info string if the log object is con figured to process messages of level WARN or higher The error code will be automatical ly prefixed with cld to avoid confusion with built in error codes 62 Log warnEnabled boolean warnEnabled Returns true if the log object is configured to sent log entries of level WARN or higher to the server onLog onLog String log Event handler invoked when logging information will be displayed in the output win dow The parameter contains the whole formatted string that will be sent to the output window in your Flash authoring environment If you
142. w was added to a synchronized table property The second argument is the new row The third argument is true if the onAddRow event is the result of a call to Table addRow in this client It is false if the event was caused by another client or by the server onRemoveAllRows onRemoveAllRows Table table boolean clientRequest Event handler invoked when all rows of a synchronized table property were removed The second argument is true if the onRemoveAllRows event is the result of a call to Table removeAllRows in this client It is false if the event was caused by another client or by the server onRemoveRow onRemoveRow Table table Object row boolean clientRequest Event handler invoked when a row of a synchronized table property was removed The second argument is the row that was removed The third argument is true if the onRemoveRow event is the result of a call to Table removeRow in this client It is false if the event was caused by another client or by the server 86 Table onUpdateRow onUpdateRow Table table Object row boolean clientRequest Event handler invoked when a row of a synchronized table property was updated The second argument is the updated row The third argument is true if the onUpdateRow event is the result of a call to Table updateRow in this client It is false if the event was caused by another client or by the server TableDefinition TableD efinition objects are used to define the
143. which objects handle which kind of messages Without filtering all incoming messages will be passed to the onMessage event handler of the M essenger object In a large application this approach may be inappropiate See the section on the M essageFilter object for details You can register an unlimited number of filters getSubscriptions Array String getSubscriptions Returns an array of all the subjects that this client has subscribed to isSubscribed boolean isSubscribed String subject Returns true if this client has subscribed to messages with the specified subject publish a 5 gt a void publish Message msg Sends a message to all users that have subscribed to the subject of this message removeListener void removeListener Object listener Removes the specified listener from this object removeFilter void removeFilter MessageFilter filter Removes the specified filter sendToAll void sendToAll Message msg Sends a message to all users who are currently logged into the server Messenger 73 sendToGroup void sendToGroup Message msg String groupName Sends a message to all the members of a particular group If you omit the optional sec ond parameter the message will be sent to the current group sendToServer void sendToServer Message msg Sends a message to the server You must write a server side GroupExtension plugin that handles th
144. y synchronized Constructor Summary new org omus Table TableDefinition def Method Summary void addAllRows Table source void addListener Object listener void addRow Object row TableDefinition getDefinition Object getRow int index void removeAllRows void removeListener Object listener Object removeRow int index int size void sort Function sortFunc void sortBy String column boolean ascending void updateRow int index Object row Event Summary onAddRow Table table Object row boolean clientRequest onRemoveAllRows Table table boolean clientRequest onRemoveRow Table table Object row boolean clientRequest onUpdateRow Table table Object row boolean clientRequest new new org omus Table TableDefinition def Creates a new table with the specified table definition The TableDefinition object can not be modified after it was used to create a table but it can be used to create more than one table with the same definition addAllRows void addAllRows Table source Adds all rows of the specified table to this table This method will only succeed if both tables have the same table definition 84 Table addListener void addListener Object listener Adds the specified object as a listener for all the events the Table object can generate addRow void addRow Object row Appends a single row to this table This method will only succeed if the specified row
145. y be created if a property or column in a table is explicitly configured as a long All other ActionScript numbers that are converted automatically will be converted to DoubleFields Constructor Summary LongField String name long value Method Summary long getLong void setLong long newValue LongField LongField String name long value Creates a new LongField with the specified name and value getLong long getLong Returns the value of this LongField as a long setLong void setLong long newValue Sets the value of this LongField to the specified long 136 LongField Message implements Cloneable Serializable A message that can be sent to Flash clients or to other users and groups on the server It corresponds to the client side M essage object The attachment is a DataRow which will be converted to a generic ActionScript object in the client and thus can carry any of the ActionScript datatypes that correspond to one of the server side DataField objects Constructor Summary Message String subject Message String subject User sender Method Summary Object clone DataRow getAttachment String getSender String getSubject Command getUndeliveredCommand void setUndeliveredCommand Command com Message Message String subject Creates a new message with the specified subject Message Message String subject User sender Creates a new message w
146. y succeeds if a group with the speci fied name already exists If you pass a valid configlD the group will be created auto matically on the server if it does not exist yet N ote that you can dynamically create an unlimited number of groups with the same configlD We get a lot of feedback from users who think that you cannot create groups dynamically because you have to con figure them on the server But each configlD corresponds to one configuration that will be shared by an unlimited number of groups with arbitrary names The third parameter can be useful if you want to set some initial values for properties of this user which would make only sense if the change into the new group succeeds Just change the values of the corresponding properties but do not call PropertySet synchronize Instead pass true as the third parameter to this method If the change succeeds the new values will be accepted and the PropertySet onSynchronize event handler will be invoked in addition to the Group onChange event handler If the attempt to change groups fails all affected prop erties will be reset close void close Closes the group so that no other users can join containsUser boolean containsUser String username Returns true if the user with the specified name is a member of this group getAllUserProperties Array PropertySet getAllUserProperties Returns an array containing the PropertySet objects for each user that is curren
147. ySet object of the group or of any user currently in this group Note that all groups must be configured in the groupConfig node in config xml on the server See the Configuration chapter for details The Group object is a singleton that will be created automatically when a user logs in It can be referenced with org omus group Method Summary void addListener Object listener void change String groupName String configlD boolean syncProps void close boolean containsUser String username Array PropertySet getAllUserProperties String getConfigID String getName PropertySet getProperties int getUserCount int getUserLimit PropertySet getUserProperties String username boolean isClosed boolean isFull void open void removeListener Object listener Event Summary onChange Object data onClose onError Error error onOpen onUserJoined PropertySet userProps onUserLeft PropertySet userProps addListener void addListener Object listener Adds the specified object as a listener for all the events the Group object can generate Group 53 a s gt 2 change void change String groupName String configID boolean syncProps Attempts to leave the current group and change into another group configlD must cor respond to an id that you used in a lt group gt node in config xml on the server You can pass null as the configlD but then the change onl
148. zation and persistence will be handled automatically so you can concentrate on the application logic Feature Overview 9 e lt m lt D Database Connectivity Oregano Server uses JDBC for database access so every database that comes with a JDBC driver can be integrated All SQL statements the server uses are included in an external XM L configuration file so you can easily make adjustments if you want to use proprietary syntax of the database you use In addition you can create your own tables and custom SQL statements Simply include them in the X M L configuration file and use them from within the ActionScript database objects of the O regano Client without writ ing a single line of server side code Logging and Statistics The server comes with an extensive logging system which is divided into several cate gories whose log level can be adjusted separately in the configuration file Statistical recordings include the number of logins per day the maximum number of concurrent connections per day and the average login time per user per day Clustering When the server load gets too high you can distribute O regano Server to more than one machine An unlimited number of secondary servers can be integrated Adding a few lines to configuration files is all you have to do to build a cluster Extensibility You can easily extend Oregano Server through the built in extension interface You can extend the functionality of a

Download Pdf Manuals

image

Related Search

Related Contents

  NEVO+1200Series User Manual  WE TRACK 24/7  Bedienungsanleitung für Zweidrahtuhrenthermostat INSTAT 2 TYP    

Copyright © All rights reserved.
Failed to retrieve file