JavaZOOM Web Site jChatBox homepage
  Software
  
Installation
  
Configuration
  
Administration
  
User guide
  
API & Extension
  
License

<< back

- XMLConnector Service -

• How does it work ?
Any client, that could be local or remote communicates to jChatBox XMLConnector service through HTTP. Client sends HTTP GET/POST requests to get chatroom information, to login/logout and to chat. XMLConnector returns standard XML formated responses that will be processed by the client.
Basically, client needs an XML parser to process responses. FLASH5+ includes a good one. For APPLETS you can use a small one like NanoXML ...
Moreover, client can also use an XSLT processor if presentation is based on XSL stylesheets.


jChatBox XML Connector Service

DTD, XML, XSL and Encoding description :
Here are DTDs and XML samples produced by XMLConnector service. Depending on XMLConnector configuration, XML files could include specific encoding, DTD pointers and XSL stylesheet processing instruction. You can also find these samples here.

DTD : manager.dtd XML SAMPLE (1)
Incoming request : xml_connector/processor.jsp?todo=manager
<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT CHATROOM EMPTY>
<!ATTLIST CHATROOM
DATE CDATA #REQUIRED
ID CDATA #REQUIRED
MAXUSERS CDATA #REQUIRED
NAME CDATA #REQUIRED
SUBJECT CDATA #REQUIRED
TOTALUSERS CDATA #REQUIRED
LANGUAGE CDATA #REQUIRED
>

<!ELEMENT MANAGER (CHATROOM+)>
<?xml version="1.0" encoding="ISO-8859-1"?>
<MANAGER>
<CHATROOM DATE="2001/08/09 20:29" ID="2" MAXUSERS="20"
NAME="FramedRoom" SUBJECT="For Testing ..." TOTALUSERS="0" LANGUAGE="english"/>
<CHATROOM DATE="2001/08/09 20:29" ID="1" MAXUSERS="20"
NAME="AppletRoom" SUBJECT="Test!" TOTALUSERS="0"
LANGUAGE="french"/>
</MANAGER>

DTD : chatroom.dtd XML SAMPLE (2)
Incoming request : xml_connector/processor.jsp?todo=chatroom
<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT CHATROOM EMPTY>
<!ATTLIST CHATROOM
DATE CDATA #REQUIRED
ID CDATA #REQUIRED
MAXUSERS CDATA #REQUIRED
NAME CDATA #REQUIRED
SUBJECT CDATA #REQUIRED
TOTALUSERS CDATA #REQUIRED
LANGUAGE CDATA #REQUIRED
>

<?xml version="1.0" encoding="ISO-8859-1"?>
<CHATROOM DATE="2001/08/09 20:29" ID="1" MAXUSERS="20" NAME="AppletRoom"
SUBJECT="Test!" TOTALUSERS="0" LANGUAGE="english"/>
DTD : chat.dtd XML SAMPLE (3)
Incoming request : xml_connector/processor.jsp?todo=refresh
<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT CHAT (MSGS, USERLIST)>
<!ATTLIST CHAT
ID CDATA #REQUIRED
PRIVATEMSG CDATA #REQUIRED
REFRESH CDATA #REQUIRED
>
<!ELEMENT MSG (#PCDATA)>
<!ATTLIST MSG
DATE CDATA #REQUIRED
FROM CDATA #REQUIRED
TYPE CDATA #REQUIRED
>

<!ELEMENT MSGS (MSG+)>
<!ELEMENT USER EMPTY>
<!ATTLIST USER
NAME CDATA #REQUIRED
>
<!ELEMENT USERLIST (USER+)>
<!ATTLIST USERLIST
CURRENT CDATA #REQUIRED
MAX CDATA #REQUIRED
>
<?xml version="1.0" encoding="ISO-8859-1"?>
<CHAT ID="2" PRIVATEMSG="true" REFRESH="10">
<MSGS>
<MSG DATE="2001/08/09 20:37" FROM="Manager" TYPE="1">Tommy</MSG>
<MSG DATE="2001/08/09 20:37" FROM="Tommy" TYPE="7">Hello !</MSG>
<MSG DATE="2001/08/09 20:37" FROM="Tommy" TYPE="7">I&apos;m Tommy !</MSG>
<MSG DATE="2001/08/09 20:37" FROM="Tommy" TYPE="7">Cool Servlet ! Bye</MSG>
<MSG DATE="2001/08/09 20:37" FROM="Tommy" TYPE="7">See ya at http://www.javazoom.net</MSG>
<MSG DATE="2001/08/09 20:38" FROM="Manager" TYPE="2">Tommy</MSG>
<MSG DATE="2001/08/09 20:38" FROM="Manager" TYPE="1">John</MSG>
<MSG DATE="2001/08/09 20:38" FROM="John" TYPE="7">Hi !</MSG>
<MSG DATE="2001/08/09 20:38" FROM="Manager" TYPE="1">XMLRobot</MSG>
<MSG DATE="2001/08/09 20:38" FROM="Manager" TYPE="2">John</MSG>
<MSG DATE="2001/08/09 20:39" FROM="XMLRobot" TYPE="7">OKOK</MSG>
<MSG DATE="2001/08/09 20:40" FROM="Manager" TYPE="1">John</MSG>
<MSG DATE="2001/08/09 20:41" FROM="John" TYPE="7">Hello XMLRobot ...</MSG>
</MSGS>

<USERLIST CURRENT="2" MAX="20">
<USER NAME="John"/>
<USER NAME="XMLRobot"/>
</USERLIST>

</CHAT>
DTD : error.dtd XML SAMPLE (4)
Incoming request : xml_connector/processor.jsp?todo=wrong
<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT ERROR (#PCDATA)>
<!ATTLIST ERROR
CODE CDATA #REQUIRED
>

<?xml version="1.0" encoding="ISO-8859-1"?>
<ERROR CODE="4">Unknown action</ERROR>
DTD : languages.dtd XML SAMPLE (5)
Incoming request : xml_connector/processor.jsp?todo=languages
<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT LANGUAGES (LANGUAGE)>
<!ATTLIST LANGUAGES
DEFAULT CDATA #REQUIRED
>
<!ELEMENT LANGUAGE EMPTY>
<!ATTLIST LANGUAGE
NAME CDATA #REQUIRED
>
<?xml version="1.0" encoding="ISO-8859-1"?>
<LANGUAGES DEFAULT="english">
<LANGUAGE NAME="french"/>
<LANGUAGE NAME="english"/>
<LANGUAGE NAME="danish"/>
<LANGUAGE NAME="german"/>
<LANGUAGE NAME="spanish"/>

</LANGUAGES>
DTD : resources.dtd XML SAMPLE (6)
Incoming request : xml_connector/processor.jsp?todo=resource&language=english
<?xml version="1.0" encoding="UTF-8"?>
<!ELEMENT RESOURCES (ELEMENT*)>
<!ELEMENT ELEMENT (NAME, VALUE)>
<!ELEMENT NAME (#PCDATA)>
<!ELEMENT VALUE (#PCDATA)>
<?xml version="1.0" encoding="ISO-8859-1"?>
<RESOURCES>
<ELEMENT>
<NAME>login.date.format</NAME>
<VALUE>yyyy/MM/dd HH:mm</VALUE>
</ELEMENT>
<ELEMENT>
<NAME>login.title</NAME>
<VALUE>Chat Login</VALUE>
</ELEMENT>
<ELEMENT>
<NAME>login.username.label</NAME>
<VALUE>NickName : </VALUE>
</ELEMENT>
[...and so on ...]

You could add following headers to XML file by configuring XMLConnector :
DTD pointer : <!DOCTYPE ROOTELM SYSTEM "afile.dtd">
Processing instruction : <?xml-stylesheet type="text/xsl" href="xsl/yourfile.xsl"?>
To do so, edit xml_connector/processor.jsp and setup Connector object as defined in jChatBox API.

More about incoming requests :

Here are descriptions of incoming HTTP requests processed by XMLConnector service.
Parameters in green are optionals. Entry point of this service is :
http://www.yourserver.com/jchatbox_uri/xml_connector/processor.jsp

Action you want to do :  HTTP
 Parameters 
Get info about all chatrooms.
You have to ask for chatrooms info to learn about chatrooms ID,
name, suject, max. users, opening date, language ...
jChatBox returns XML data matching to manager.dtd.
todo=manager
Get info about only one chatroom.
You could ask info for one chatroom identified by its ID.
jChatBox returns XML data matching to chatroom.dtd.
todo=chatroom
id=1
Login to a chatroom.
You need to join with an available name before chatting
in a chatroom identified by its ID.
jChatBox returns XML data matching to chat.dtd.
todo=login
name=John
chatrooms=1
password=abcd123
newonly=true
Send message to everyone in a chatroom (*).
You send a msg to ALL users in the chatroom you've joined.
jChatbox knows which chatroom you've joined.
It returns XML data matching to chat.dtd.
todo=chat
to=ALL
msg=Hello all !
newonly=true
Send a private message to XYZ in a chatroom (*).
You send a msg to an user identified by its name in the chatroom
you've joined. jChatbox knows which chatroom you've joined.
It returns XML data matching to chat.dtd.
todo=chat
to=XYZ
msg=Hello mr XYZ!
newonly=true
Just refresh the content of the chatoom (*).
You send a msg to ALL users in the chatroom you've joined.
jChatbox knows which chatroom you've joined.
It returns XML data matching to chat.dtd.
todo=refresh
newonly=true
Logout the chatroom (*).
You logout by killing your session from the chatroom you've joined.
jChatbox knows which chatroom you've joined.
It returns XML data matching to manager.dtd.
todo=logout
Quit the chatroom (*).
You logout (without killing your session) from the chatroom you've joined.
jChatbox knows which chatroom you've joined.
It returns XML data matching to manager.dtd.
todo=quit
Get supported languages.
You could ask jChatBox for supported languages.
It returns XML data matching to languages.dtd.
todo=languages
Get language resources.
You could ask jChatBox resources given a supported language. All resources' names (e.g. login.chatroom.label) are avaible in WEB-INF/conf/resources_en.xml
It returns XML data matching to resources.dtd.
todo=resource
language=spanish

(*) means that you have to be logged in the chatroom.

For instance, to get info about all chatrooms, you could send your request through the following URL :
http://yourserver.com/jchatbox/xml_connector/processor.jsp?todo=manager

To login the chatroom identified by ID = 1, you could try :
http:/yourserver.com/jchatbox/xml_connector/processor.jsp?todo=manager&name=John&chatrooms=1

To send a message to everyone in the chatroom you've joined, you could have :
http:/yourserver.com/jchatbox/xml_connector/processor.jsp?todo=chat&to=ALL&msg=Hello%20all%21

To keep synchronized with the chatroom you've joined, you must have :
http:/yourserver.com/jchatbox/xml_connector/processor.jsp?todo=refresh

To keep synchronized with the chatroom you've joined and get only new messages since the last access, you must have :
http:/yourserver.com/jchatbox/xml_connector/processor.jsp?todo=refresh&newonly=true
Note: This feature is used in Applet and FLASH5+ clients.

To logout from the chatroom you've joined, you could try :
http:/yourserver.com/jchatbox/xml_connector/processor.jsp?todo=logout

To get supported languages list, you could try :
http:/yourserver.com/jchatbox/xml_connector/processor.jsp?todo=languages

To get resources for a given supported language, you could try :
http:/yourserver.com/jchatbox/xml_connector/processor.jsp?todo=resource&language=spanish


XML Connector FAQ :

Could I use my customized login module with XML Connector service ?
Sure, edit xml_connector/processor.jsp and set your login module through Connector.setLoginModule("yourLogin.module"). Default is
jChatBox.Service.UserLogin.
s
How to modify XML encoding to support more charset ?
Edit xml_connector/processor.jsp and set your encoding (e.g. UTF-8) through Connector.setXMLEncoding("anEncoding") and response.setContentType("text/xml; charset=
anEncoding"). Default is ISO-8859-1.

How to enable/disable DTD header from XML files ?

Edit xml_connector/processor.jsp and enable/disable through Connector.setDTDEnabled(true/false) method.

How to add XSL stylesheet processing instruction in XML files header ?
Edit xml_connector/processor.jsp and enable/disable through
Connector.setXSL.....("URI to XSL stylesheet") methods. null parameter means that stylesheet processing instruction is disabled.

Where could I find more information about XMLConnector API ?
Check out jChatBox API - Service package. Try this link.
You can also check out JavaZOOM's online forums (JSP or XML forum) :
http://www.javazoom.net/services/forums/index.jsp

Does XML Connector compliant with SOAP ?
No, even if we have remote "procedures" with XML over HTTP, XMLConnector is not SOAP compliant. It's just a way to get jChatBox chatrooms info/content formated as standard XML.

[News] [Applets] [Servlets] [Services] [Projects] [Links] [About]

Copyright © JavaZOOM 1999-2004

Java is a trademark of Sun Microsystems,Inc. All other company and/or product names are the property of their respective owners.