-
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'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.
|