org.mmbase.applications.community.builders
Class Channel

java.lang.Object
  org.mmbase.module.core.MMTable
      org.mmbase.module.core.MMObjectBuilder
          org.mmbase.applications.community.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:

$Id: Channel.java,v 1.22 2004/01/19 17:27:09 michiel Exp $

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

AGE_PARAMETERS, broadcastChanges, database, DEFAULT_ALINEA, DEFAULT_EOL, description, descriptions, fields, GUI_PARAMETERS, listCache, nodeCache, 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	activate() Activates the channel builder for the community application by associating it with other community builders and opening all communities.
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) Deprecated. use leave(org.mmbase.module.core.MMObjectNode, org.mmbase.module.core.MMObjectNode) instead
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.
void	setDefaults(MMObjectNode node) Sets defaults for a node.
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, count, create, createAlias, delete, 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, getFunctionParameters, getGUIIndicator, getHardNode, getHardNode, getHTML, getInitParameter, getInitParameters, getList, getLocaleGUIIndicator, getLocaleGUIIndicator, getMachineName, getMaintainer, getMMBase, getNewNode, getNewTmpNode, getNextField, getNextField, getNode, getNode, getNode, getNode, getNodes, getNodes, getNodeType, getNumberFromName, getObjectType, getObjectValue, getParameterDefinition, getParentBuilder, getPluralName, getPluralName, getPluralNames, getQuery, getQuery, getQuery, getRawNodes, getRelations_main, getSearchAge, getShort, getShortedByte, getShortedText, getSingularName, getSingularName, getSingularNames, getSmartPath, getSortedFields, getSortedListFields, getTmpNode, getURLEncode, getVersion, getWAP, getXMLPath, hashCode, hostname_function, insert, insert, insertDone, isExtensionOf, isNodeCached, isVirtual, nodeLocalChanged, nodeRemoteChanged, preCommit, preEdit, process, processSearchResults, putTmpNode, readSearchResults, removeField, removeNode, removeRelations, removeSyncNodes, 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, setDescription, setDescriptions, setInitParameter, setMaintainer, setMMBase, setParentBuilder, setPluralNames, setSearchAge, setSingularNames, setTableName, setUniqueValue, setUniqueValue, setValue, setValue, setVersion, setXMLPath, setXMLValues, signalNewObject, testValidData, toString, toString, toXML, updateFields, waitUntilNodeChanged, wrap

Methods inherited from class org.mmbase.module.core.MMTable

created, getFullTableName, getTableName, 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.

See Also:

Constant Field Values

WANT_OPEN

public static final int WANT_OPEN

Open state : the channel is waiting to be opened.

See Also:

Constant Field Values

READ_ONLY

public static final int READ_ONLY

Open state : the channel is open for read-only.

See Also:

Constant Field Values

OPEN

public static final int OPEN

Open state : the channel is open.

See Also:

Constant Field Values

FAILED

public static final int FAILED

Join state : the user cannot be connected to the channel.

See Also:

Constant Field Values

CHANNEL_FULL

public static final int CHANNEL_FULL

Join state : the channel is full.

See Also:

Constant Field Values

CONNECTED

public static final int CONNECTED

Join state : the user is connected to the channel.

See Also:

Constant Field Values

ALREADY_CONNECTED

public static final int ALREADY_CONNECTED

Join state : the user is already connected to the channel.

See Also:

Constant Field Values

DISCONNECTED

public static final int DISCONNECTED

Join state : the user is logged out of the channel.

See Also:

Constant Field Values

F_OPEN

public static final java.lang.String F_OPEN

Field : open

See Also:

Constant Field Values

F_MAXUSERS

public static final java.lang.String F_MAXUSERS

Field : maxusers

See Also:

Constant Field Values

F_STATE

public static final java.lang.String F_STATE

Field : state

See Also:

Constant Field Values

F_SESSION

public static final java.lang.String F_SESSION

Field : session

See Also:

Constant Field Values

F_READLOGIN

public static final java.lang.String F_READLOGIN

Virtual Field : readlogin

See Also:

Constant Field Values

F_WRITELOGIN

public static final java.lang.String F_WRITELOGIN

Virtual Field : writelogin

See Also:

Constant Field Values

F_HASMOODS

public static final java.lang.String F_HASMOODS

Virtual Field or Function : hasmoods or hasmoods()

See Also:

Constant Field Values

STATE_READ_LOGIN

public static final int STATE_READ_LOGIN

state : read login bit

See Also:

Constant Field Values

STATE_WRITE_LOGIN

public static final int STATE_WRITE_LOGIN

state : write login bit

See Also:

Constant Field Values

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. This step can be skipped, to speed up startup of the server, by specifying the property open-channels-on-startup in the Channel builder configuration, and setting it to false.

Overrides:

init in class MMObjectBuilder

Returns:

true if init was completed, false if uncompleted.

See Also:

MMObjectBuilder.create()

activate

public boolean activate()

Activates the channel builder for the community application by associating it with other community builders and opening all communities.

Returns:

true if activation worked

open

public boolean open(MMObjectNode channel)

Opens the channel.

Parameters:

channel - The channel to open.

Returns:

true if opening the channel was successfull.

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

Returns:

true if opening the channel was successfull.

close

public boolean close(MMObjectNode channel)

Closes the channel.

Parameters:

channel - The channel to close.

Returns:

true if closing the channel was successfull.

readonly

public boolean readonly(MMObjectNode channel)

Makes a channel read only.

Parameters:

channel - The channel to affect.

Returns:

true if changing the channel open status was successfull.

isOpen

public java.lang.String isOpen(MMObjectNode channel)

Returns if a channel is open, closed or readonly.

Parameters:

channel - 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:

channel - 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:

channel - 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

recorder - 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

filepath - 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)

Deprecated. use leave(org.mmbase.module.core.MMObjectNode, org.mmbase.module.core.MMObjectNode) instead

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.

• CHANNEL should containt the number or alias of the channel node
• TYPE may conmtain the user's object type. The default is the value specified in the builder properties
• FIELDS should contain the names of the fields whose values to return
• SORTFIELDS may contain the names of the fields to sort on
• SORTDIRS may contain the sort-order for the fields in SORTFIELDS

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.

• CHANNEL should containt the number or alias of the channel node
• TYPE may conmtain the user's object type. The default is the value specified in the builder properties
• FIELDS should contain the names of the fields whose values to return
• SORTFIELDS may contain the names of the fields to sort on
• SORTDIRS may contain the sort-order for the fields in SORTFIELDS

Parameters:

params - contains the parameters for this list command.

Returns:

a vector with the user nodes.

setDefaults

public void setDefaults(MMObjectNode node)

Description copied from class: MMObjectBuilder

Sets defaults for a node. Fields "number", "owner" and "otype" are not set by this method.

Overrides:

setDefaults in class MMObjectBuilder

Parameters:

node - The node to set the defaults of.

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:

channel - 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:

• channelnumber-OPEN - opens the channel
• channelnumber-CLOSE - closes the channel
• channelnumber-ISOPEN - returns if a channel is "open", "closed" or "readonly";
• channelnumber-DELALLMESSAGES - deletes all posted messages in the channel
• channelnumber-NEWSEQ - returns a new sequence number for in the channel
• channelnumber-JOIN-usernumber - connects the user to the channel.
• channelnumber-LEAVE-usernumber - disconnects a user from the channel.
• channelnumber-STILLACTIVE-usernumber - resets the time-out before the user is automatically disconnected from the channel.

Overrides:

replace in class MMObjectBuilder

Parameters:

sp - the current scanpage 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

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