org.mmbase.module.builders
Class Channel

java.lang.Object
  |
  +--org.mmbase.module.core.MMTable
        |
        +--org.mmbase.module.core.MMObjectBuilder
              |
              +--org.mmbase.module.builders.Channel

public class Channel
extends MMObjectBuilder

The channel builder maintains channels for forums and chats. Each channel is linked to a Community, which defines some properties for the channel (such as whether it is a forum or a chatbox). Users can join a channel (up to a registered amount of users), and post messages to it (stored in the Message builder).
The main tasks defined in this builder are ways to open and close a channel, join users, generate sequence numbers (which defines the order for a message), and remove messages belonging to a channel. Optionally, a recorder (java.io.Writer) object can be opened for a channel. The Message builder uses these writers for logging chats. (Note that is would be possible to make a Writer that stores data in a node or a builder, but this has not been implemented yet). XXX: Currently, recorder info is NOT stored in the channel. A recorder has to be activated manually (using $MOD-channelnr-RECORD-FILE-filname).

Version:
21 May 2001
Author:
Dirk-Jan Hoekstra, Pierre van Rooden

Field Summary
static int ALREADY_CONNECTED
          Join state : the user is already connected to the channel.
static int CHANNEL_FULL
          Join state : the channel is full.
static int CLOSED
          Open state : the channel is closed.
static int CONNECTED
          Join state : the user is connected to the channel.
static int DISCONNECTED
          Join state : the user is logged out of the channel.
static java.lang.String F_HASMOODS
          Virtual Field or Function : hasmoods or hasmoods()
static java.lang.String F_MAXUSERS
          Field : maxusers
static java.lang.String F_OPEN
          Field : open
static java.lang.String F_READLOGIN
          Virtual Field : readlogin
static java.lang.String F_SESSION
          Field : session
static java.lang.String F_STATE
          Field : state
static java.lang.String F_WRITELOGIN
          Virtual Field : writelogin
static int FAILED
          Join state : the user cannot be connected to the channel.
static int OPEN
          Open state : the channel is open.
static int READ_ONLY
          Open state : the channel is open for read-only.
static int STATE_READ_LOGIN
          state : read login bit
static int STATE_WRITE_LOGIN
          state : write login bit
static int WANT_OPEN
          Open state : the channel is waiting to be opened.
 
Fields inherited from class org.mmbase.module.core.MMObjectBuilder
broadcastChanges, database, DEFAULT_ALINEA, DEFAULT_EOL, description, descriptions, fields, nodeCache, obj2type, OBJ2TYPE_MAX_SIZE, oType, REPLACE_CACHE, searchAge, sortedDBLayout, TEMPNODE_DEFAULT_SIZE, TemporaryNodes, virtual
 
Fields inherited from class org.mmbase.module.core.MMTable
mmb, tableName
 
Constructor Summary
Channel()
          Constructor
 
Method Summary
 boolean close(MMObjectNode channel)
          Closes the channel.
 MMObjectNode communityParent(MMObjectNode channel)
          Returns to which community a channel belongs.
protected  java.lang.Object executeFunction(MMObjectNode node, java.lang.String function, java.lang.String field)
          Executes a function on the field of a node, and returns the result.
 java.lang.String getDefaultUrl(int src)
          Ask URL from related community and append the channel number to the URL.
 java.lang.String getGUIIndicator(java.lang.String field, MMObjectNode node)
          What should a GUI display for this node/field combo.
 java.util.Vector getListUsers(MMObjectNode channel, java.lang.String usertype, java.util.Comparator compareUsers, int offset, int max)
          Retrieve a sorted list of users connected to a channel.
 java.util.Vector getListUsers(StringTagger params)
          Retrieve a list of users connected to a channel.
 int getNewSequence(MMObjectNode channel)
           
 java.util.Vector getNodeListUsers(java.util.Map params)
          Retrieve a list of users connected to a channel.
 java.io.Writer getRecorder(int channel)
          Returns the recorder for this channel.
 java.lang.Object getValue(MMObjectNode node, java.lang.String field)
          Provides additional functionality when obtaining field values.
 boolean init()
          Initializes the Channel builder.
 java.lang.String isOpen(MMObjectNode channel)
          Returns if a channel is open, closed or readonly.
 int join(MMObjectNode user, MMObjectNode channel)
          Connects a user to a channel by making a temporary relation between them.
 int leave(MMObjectNode user, MMObjectNode channel)
          Disconnects a user from a channel.
 int logout(MMObjectNode user, MMObjectNode channel)
          Disconnects a user from a channel.
 boolean open(MMObjectNode channel)
          Opens the channel.
 boolean open(MMObjectNode channel, MMObjectNode community)
          Opens the channel.
 boolean readonly(MMObjectNode channel)
          Makes a channel read only.
 void removeAllMessages(MMObjectNode channel)
          Removes all messages posted in the channel.
 java.lang.String replace(scanpage sp, java.util.StringTokenizer tok)
          Handles the $MOD-MMBASE-BUILDER-channel- commands.
 java.io.Writer startRecorder(int channel, java.lang.String filepath)
          Start the recording session of a channel, using a file to stream the output to.
 java.io.Writer startRecorder(int channel, java.io.Writer recorder)
          Start the recording session of a channel.
 void stopRecorder(int channel)
          Stop the recording session of a channel.
 void userStillActive(MMObjectNode user, MMObjectNode channel)
          Registers a user as still being active.
 
Methods inherited from class org.mmbase.module.core.MMObjectBuilder
addField, addLocalObserver, addRemoteObserver, buildSet, checkAddTmpField, commit, convertMMNode2SQL, count, create, createAlias, created, deleteNodeCache, drop, equals, equals, executeFunction, fieldLocalChanged, getAge, getAliasedNode, getAncestors, getCacheNumbers, getCacheSize, getCacheSize, getClassName, getConfigFile, getDBByte, getDBKey, getDBState, getDBText, getDBType, getDefaultTeaser, getDescendants, getDescription, getDescription, getDescriptions, getEditFields, getField, getFieldNames, getFields, getFields, getFullTableName, getFunctionParameters, getGUIIndicator, getHardNode, getHardNode, getHTML, getInitParameter, getInitParameters, getList, getLocaleGUIIndicator, getLocaleGUIIndicator, getMachineName, getMaintainer, getNewNode, getNewTmpNode, getNextField, getNextField, getNode, getNode, getNode, getNode, getNodes, getNodeType, getNumberFromName, getObjectType, getObjectValue, getParentBuilder, getPluralName, getPluralName, getPluralNames, getQuery, getQuery, getQuery, getRelations_main, getSearchAge, getShort, getShortedByte, getShortedText, getSingularName, getSingularName, getSingularNames, getSmartPath, getSortedFields, getSortedListFields, getTableName, getTmpNode, getURLEncode, getVersion, getWAP, getXMLPath, hashCode, hostname_function, insert, insert, insertDone, isExtensionOf, isNodeCached, isVirtual, nodeLocalChanged, nodeRemoteChanged, preCommit, preEdit, process, putTmpNode, readSearchResults, removeField, removeNode, removeRelations, removeTmpNode, safeCache, safeCommit, safeInsert, search, search, search, searchIn, searchIn, searchIn, searchList, searchList, searchNumbers, searchVector, searchVector, searchVector, searchVector, searchVectorIn, searchVectorIn, searchVectorIn, searchVectorIn, searchWithWhere, sendFieldChangeSignal, setDBLayout_xml, setDefaults, setDescription, setDescriptions, setInitParameter, setMaintainer, setMMBase, setParentBuilder, setPluralNames, setSearchAge, setSingularNames, setTableName, setValue, setValue, setVersion, setXMLPath, setXMLValues, signalNewObject, testValidData, toString, toString, toXML, updateFields, waitUntilNodeChanged, wrap
 
Methods inherited from class org.mmbase.module.core.MMTable
size
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

CLOSED

public static final int CLOSED
Open state : the channel is closed.

WANT_OPEN

public static final int WANT_OPEN
Open state : the channel is waiting to be opened.

READ_ONLY

public static final int READ_ONLY
Open state : the channel is open for read-only.

OPEN

public static final int OPEN
Open state : the channel is open.

FAILED

public static final int FAILED
Join state : the user cannot be connected to the channel.

CHANNEL_FULL

public static final int CHANNEL_FULL
Join state : the channel is full.

CONNECTED

public static final int CONNECTED
Join state : the user is connected to the channel.

ALREADY_CONNECTED

public static final int ALREADY_CONNECTED
Join state : the user is already connected to the channel.

DISCONNECTED

public static final int DISCONNECTED
Join state : the user is logged out of the channel.

F_OPEN

public static final java.lang.String F_OPEN
Field : open

F_MAXUSERS

public static final java.lang.String F_MAXUSERS
Field : maxusers

F_STATE

public static final java.lang.String F_STATE
Field : state

F_SESSION

public static final java.lang.String F_SESSION
Field : session

F_READLOGIN

public static final java.lang.String F_READLOGIN
Virtual Field : readlogin

F_WRITELOGIN

public static final java.lang.String F_WRITELOGIN
Virtual Field : writelogin

F_HASMOODS

public static final java.lang.String F_HASMOODS
Virtual Field or Function : hasmoods or hasmoods()

STATE_READ_LOGIN

public static final int STATE_READ_LOGIN
state : read login bit

STATE_WRITE_LOGIN

public static final int STATE_WRITE_LOGIN
state : write login bit
Constructor Detail

Channel

public Channel()
Constructor
Method Detail

init

public boolean init()
Initializes the Channel builder.
Creates references to other required builders and relation roles.
Also opens all channels whose open field is set to OPEN or WANT_OPEN .
Overrides:
init in class MMObjectBuilder
Following copied from class: org.mmbase.module.core.MMObjectBuilder
Returns:
true if init was completed, false if uncompleted.
See Also:
MMObjectBuilder.create()

open

public boolean open(MMObjectNode channel)
Opens the channel.
Parameters:
channel - The channel to open.

open

public boolean open(MMObjectNode channel,
                    MMObjectNode community)
Opens the channel.
Parameters:
channel - The channel to open.
community - The community with this channel's settings

close

public boolean close(MMObjectNode channel)
Closes the channel.
Parameters:
channel - The channel to close.

readonly

public boolean readonly(MMObjectNode channel)
Makes a channel read only.
Parameters:
channel - The channel to affect.

isOpen

public java.lang.String isOpen(MMObjectNode channel)
Returns if a channel is open, closed or readonly.
Parameters:
The - channel of which the open state is asked.
Returns:
the state of the channel, described as a String

getNewSequence

public int getNewSequence(MMObjectNode channel)
Parameters:
The - channel that has to give out a new sequence number.
Returns:
A new sequence number for a message that's want to get postend in this channel.

removeAllMessages

public void removeAllMessages(MMObjectNode channel)
Removes all messages posted in the channel. XXX: does not work for chats.
Parameters:
The - channel whose messages have to be removed.

getRecorder

public java.io.Writer getRecorder(int channel)
Returns the recorder for this channel. The recorder is currently only used in chats.
Parameters:
channel - the channel to record
Returns:
a Writer with which to record data, or null if the recorder doesn't exist.

startRecorder

public java.io.Writer startRecorder(int channel,
                                    java.io.Writer recorder)
Start the recording session of a channel.
Parameters:
channel - the channel to record
out - a Writer to record to.
Returns:
the Writer that will record the messages

startRecorder

public java.io.Writer startRecorder(int channel,
                                    java.lang.String filepath)
Start the recording session of a channel, using a file to stream the output to.
Parameters:
channel - the channel to record
file - the file to record to.
Returns:
the Writer that will record the messages

stopRecorder

public void stopRecorder(int channel)
Stop the recording session of a channel.
Parameters:
channel - the channel being recorded

join

public int join(MMObjectNode user,
                MMObjectNode channel)
Connects a user to a channel by making a temporary relation between them. If the user is already connected to another channel of the same community the old connection is closed.
Parameters:
user - the node representing the user that tries to join the channel.
channel - the channel to join
Returns:
CHANNEL_FULL if there's no room in the channel, CONNECTED if the connection is made, and FAILED if an error occurred. If the user is already connected to the channel ALREADY_CONNECTED is returned.

logout

public int logout(MMObjectNode user,
                  MMObjectNode channel)
Disconnects a user from a channel. Removes the temporary relations between the user and the channel.
Parameters:
user - The user to disconnect.
channel - The channel to disconnect from.
Returns:
DISCONNECTED if the user was successfully disconnected, FAILED if an error occurred.

leave

public int leave(MMObjectNode user,
                 MMObjectNode channel)
Disconnects a user from a channel. Removes the temporary relations between the user and the channel.
Parameters:
user - The user to disconnect.
channel - The channel to disconnect from.
Returns:
DISCONNECTED if the user was successfully disconnected, FAILED if an error occurred.

userStillActive

public void userStillActive(MMObjectNode user,
                            MMObjectNode channel)
Registers a user as still being active. Tells the associated NodeBreaker to extend the relation between the user and the channel for another period of time.
Parameters:
user - the node representing the user
channel - the channel to which the user is connected

getListUsers

public java.util.Vector getListUsers(StringTagger params)
Retrieve a list of users connected to a channel. The params parameter contains the parameters for the list.
Parameters:
params - contains the parameters for this list command.
Returns:
a vector with the (string) values of the requested fields, per user.

getNodeListUsers

public java.util.Vector getNodeListUsers(java.util.Map params)
Retrieve a list of users connected to a channel. The params parameter contains the parameters for the list.
Parameters:
params - contains the parameters for this list command.
Returns:
a vector with the user nodes.

getListUsers

public java.util.Vector getListUsers(MMObjectNode channel,
                                     java.lang.String usertype,
                                     java.util.Comparator compareUsers,
                                     int offset,
                                     int max)
Retrieve a sorted list of users connected to a channel.
Parameters:
channel - the channel
usertype - the type of the userobjects to retrieve
compareUsers - a Comparator used for sorting. null means the result is not no sorted
Returns:
a vector with the nodes of the users.

communityParent

public MMObjectNode communityParent(MMObjectNode channel)
Returns to which community a channel belongs.
Parameters:
The - channel node
Returns:
The community of the channel, or null if the channel is not associated with a community.

getValue

public java.lang.Object getValue(MMObjectNode node,
                                 java.lang.String field)
Provides additional functionality when obtaining field values. This method is called whenever a Node of the builder's type fails at evaluating a getValue() request (generally when a fieldname is supplied that doesn't exist).
The following virtual fields are calculated:
readlogin - returns true when a user has to log on before he can read messages, false otherwise.
writelogin - returns true when a user has to log on before he can post a message, false otherwise.
hasmoods - returns "yes" when there are moods related to the channel, "no" otherwise.
It is also possible to specify hasmoods as a function. hasmoods() performs the same test, but returns a Boolean object (which evaluates to "true" and "false" when used referenced as a string) instead of "yes"/"no". This method is preferred for use with the MMCI.
Overrides:
getValue in class MMObjectBuilder
Parameters:
node - the node whose fields are queried
field - the fieldname that is requested
Returns:
the result of the call, null if no valid functions or virtual fields could be determined.

executeFunction

protected java.lang.Object executeFunction(MMObjectNode node,
                                           java.lang.String function,
                                           java.lang.String field)
Executes a function on the field of a node, and returns the result. This method is called by the builder's getValue(org.mmbase.module.core.MMObjectNode, java.lang.String) method. Functions implemented are readlogin(), writelogin() and hasmoods().
Overrides:
executeFunction in class MMObjectBuilder
Parameters:
node - the node whose fields are queries
field - the fieldname that is requested
Returns:
the result of the 'function', or null if no valid functions could be determined.

replace

public java.lang.String replace(scanpage sp,
                                java.util.StringTokenizer tok)
Handles the $MOD-MMBASE-BUILDER-channel- commands. The commands to use are:
Overrides:
replace in class MMObjectBuilder
Parameters:
scanpage - the current page context
tok - the tokenized command
Returns:
the result of the command as a String

getDefaultUrl

public java.lang.String getDefaultUrl(int src)
Ask URL from related community and append the channel number to the URL.
Overrides:
getDefaultUrl in class MMObjectBuilder
Following copied from class: org.mmbase.module.core.MMObjectBuilder
Parameters:
src - the number of the node to obtain the url from
Returns:
the basic url as a String, or null if unknown.

getGUIIndicator

public java.lang.String getGUIIndicator(java.lang.String field,
                                        MMObjectNode node)
What should a GUI display for this node/field combo. Fields converted are ""session" (returns yes/no) and ""state", which returns a description of the login condition.
Overrides:
getGUIIndicator in class MMObjectBuilder
Parameters:
node - The node to display
field - the name field of the field to display
Returns:
the display of the node's field as a String, null if not specified


MMBase build 1.6.5.20030923