Work in progress, feel free to contribute!
Discussion about server communication Vs. client communication#
Scenario 1: Say that I don't want to share anything with any other users (no server interaction), I just want to retrieve a certain amount of information from a webservice and show it in a Swing App that only I can see. Can I create the external connection directly from the client? or, in other words, am I restricted due to transactions or threading, etc.?
If I wanted at some stage to share info with other users, I would go on and use the server support to do so (MOs, messages, and so on).
Scenario 2: If the server is the one connecting in order to make some info available to everyone in-world, then a darkstar service is the only way to go (unless you download to client and from client send to server, but you depend on a client being logged in for the thing to work!).
In Scenario 1, you are using normal Java calls on the client, so there are no restrictions in terms of threading or networking. Darkstar is not involved in the client at all, so there are no timeouts and no relevance of Darkstar services. Basically the client can fetch data in whatever manner it sees fit, and share some or all of that with other clients via the server.
An example of Scenario 1 would be a flickr viewer(TODO: add link). The user enters a query, and their client then sends that as a photo query to flickr. Flickr returns a set of photo URLs to the client. The client then sends messages to the server to create a bunch of image viewer cells for the photos, which are visibile to everyone because the image cells include the URL of the photos.
In Scenario 2, the actual work is performed on the server, by way of a Darkstar service. This is subject to all the restrictions of Darkstar programming, including threading and transactions. The advantage of this scenario is that the querying is only done once, and everyone sees the same results.
An example of Scenario 2 would be access to a relational database. Since individual clients can't connect to the database directly, the server connects to the database and relays results to clients.
NOTE: Technically, there is no reason your database couldn't be accessible to every client. Realistically, databases are usually tightly controlled behind firewalls, with limited usernames and passwords for access. So rather than making your database available outside the firewall, giving every client credentials to log in, and requiring an extra network connection, it is usually better to have the server access the database and feed the results to clients.
There is also a Scenario 3, which is kind of a hybrid of 1 and 2. In this case, you have a separate process that talks to the external service and then sends messages to the Darkstar server. It has the benefits of both scenarios: you can use any library without worrying about threading or transactions, but because there is single, permanent process, it can supply data for everyone in the world via a single connection. The only downside is that you have to manage the separate process. This is how, for example, the Shared Application Server works. You could imagine plugging into XMPP chat servers this way as well.
Alternatively, a custom client (Scenario 3) could run behind the firewall and access the database as needed. That way you wouldn't have to write a Darkstar service, but you could still access the database in a controlled manner.
(Jon)I've always referred to Scenario 3 as a "custom client" or "standalone client". Reading this discussion is making me think that "bridge" might be a better term -- the custom client in this case is a bridge between the database and Darkstar.
Darkstar services -- do you really need one?#As per the discussion above, you will only need a darkstar service if you want to make connections from the server, and then distribute to the clients (through normal channels). Please note that this can also be avoided by using scenario 3. Darkstar services are hard to code (TODO: add links to tutorials).
This is a short tutorial on how to create a simple REST client within a Cell inworld that can talk to a web application. REST client sample module
Threads on wiki related to this#
TODO: add links to the sql-service and service-test modules.