 |
|
|
|||
| |||
|
SpaceKit for Java, page 3
1 Introduction
2 The Blocks SpaceKit for Java Client
» Connecting and Channel Creation
4 Client Examples
5 The Blocks SpaceKit for Java Server: SpaceBxxd
6 SpaceBxxd - Responses
7 Localization Class Structure and Utilities
8 Reference
this article in RFC-2629 formats The Blocks SpaceKit for Java Client
Channels, Requests, Parsers and Tracing
Connecting A single instance of the SpaceServer class exists for each socket connection to the space server. To open a connection to the server sqa.invisible.net on the default port (port 10288):
SpaceServer server = new SpaceServer("sqa.invisible.net"); SpaceResponse greeting = server.connect();The connect
()waits for the connection to complete, returning the greeting. To get a list of available profiles, use the getProfiles()method:
String[] profiles = greeting.getProfiles(); for(int k=0;k<profiles.length;++k) System.out.println(profiles[k]);The profile array generally contains the following profiles:
Profile: http://xml.resource.org/profiles/sasl/ANONYMOUS Profile: http://xml.resource.org/profiles/SEP Profile: http://xml.resource.org/profiles/NULL/ECHO Profile: http://xml.resource.org/profiles/NULL/SINK Profile: http://xml.resource.org/profiles/sasl/OTPLocalization and features are accessible via the getLocalize
()and getFeatures()methods, respectively.Establishing the connection can throw both a SpaceException and a SpaceTimeout.
Connecting With Localization When establishing the connection, an optional localization can be specified. The specification may include multiple languages. The order within the localize list is in priority order, left to right. If the server is unable to return messages in any of these languages, it defaults to "i-default."
The following is an example of connecting with three preferred languages, in priority order:"
SpaceResponse greeting = server.connect("fr en en-us",true);
Channel Creation Once a connection exists, a SpaceChannel must be created to the server to make subsequent requests. Two types of channels exist: Non-authenticated and authenticated channels.
Non-Authenticated Channels A non-authenticated channel is created by passing a valid non-authenticating profile to getChannel
():
SpaceChannel channel = server.getChannel(SpaceProfile.sep);The permission level of a non-authenticated channel is determined by the server.
SASL Authenticated Channels Two types of SASL authenticated channels exist: Anonymous and OTP (One Time Password).
SASL Anonymous Authenticated Channels A SASL anonymous channel is created by passing a valid SpaceAuthenticator associated with the SASL anonymous profile:
SpaceAuthenticator authenticator = new SpaceAuthenticatorSasl(SpaceProfile.saslAnonymous); authenticator.set("authenticator","yourusernamehere"); SpaceChannel channel = server.getChannel(authenticator);
SASL OTP (One-Time Password) Authenticated Channels A SASL OTP autheticated channel is created by passing a valid SpaceAuthenticator associated with the SASL OTP profile:
SpaceAuthenticator authenticator = new SpaceAuthenticatorSasl(SpaceProfile.saslOtp); authenticator.set("authenticator","yourusernamehere"); authenticator.set("passphrase","yourpassphrasehere"); SpaceChannel channel = server.getChannel(authenticator);
Requests Once a valid channel is open, requests may be made to the space server using the Blocks Simple Exchange Profile (SEP). A typical "fetch" sequence looks like:
StringBuffer sep = new StringBuffer(); sep.append("<fetch>\r\n"); sep.append("<union>\r\n"); sep.append("<intersect>\r\n"); sep.append("<compare subtree='doc.edgar' operator='contains' caseSensitive='false'>"); sep.append("<path><element property='state.of.incorporation' /></path>\r\n"); sep.append("<value>IN</value>\r\n"); sep.append("</compare>\r\n"); sep.append("</intersect>\r\n"); sep.append("</union>\r\n"); sep.append("</fetch>\r\n"); SpaceResponse response = channel.request(sep.toString(),false); //...can do other things here while fetch is processing channel.wait(response); //...use the response results using response.toString() channel.free(response);See "Responses and Flow Control" for an explanation of channel.wait
().
XML Parsers The response contains XML that may act as input to any XML parser. For example, the following creates a DOM document using the Apache-Xerces (xml.apache.org) parser:
InputStream in = response.getInputStream(); DOMParser parser = new DOMParser(); parser.parse(new InputSource(in)); DocumentImpl document = (DocumentImpl)parser.getDocument();
Responses and Flow Control A SpaceResponse returns from many of the SpaceServer methods, such as connect
(), start()and request(). All of these methods take an optional boolean "wait" argument. If set to true, the returned response is guaranteed to be "complete" unless an error has occurred. You can check to see if the response is an error using the "isError()" method. If "isError()" returns true, the methods "getErrorCode()" and "getErrorText()" returns the int error code and String error text, respectively.If the optional "wait" argument is specified to be false, the requesting method returns immediately with an "incomplete" response while a separate thread continues to receive the response. Any number of incomplete requests can exist concurrently. At any time, whether a response is "complete" or "incomplete," you can check the state of the response using methods such as "isIncomplete
()" and "getLength()." See the reference section for a complete list.To wait for the response to complete, use the wait method from the SpaceServer:
channel.wait(response);The wait
()can be specified with an optional timeout. When wait()returns it is guaranteed to be complete unless an error occurs.After the wait is complete, the response is removed from the response queue, but the content of the response is preserved, accessible with either "getString
()" or "getInputStream()." To mark the content as no longer needed, close the response using:
channel.free(response);
Exceptions Two exceptions are described in the Reference section: SpaceException and SpaceTimeout.
Tracing Tracing is a very helpful debugging tool to view the response queue set by doing:
server.setTrace(true);Since responses are often broken up into multiple frames, during tracing every time a frame arrives, the status of the entire response queue is shown to System.err, looking something like:
------------------------------------------------------------------ : ID : Channel : Serial : Length : Frames : Complete : Error : ------------------------------------------------------------------ : 0 : 7 : 23 : 0 : 0 : No : No : : 1 : 7 : 22 : 0 : 0 : No : No : : 2 : 7 : 21 : 0 : 0 : No : No : : 3 : 7 : 20 : 0 : 0 : No : No : : 4 : 7 : 19 : 0 : 0 : No : No : : 5 : 7 : 18 : 0 : 0 : No : No : : 6 : 7 : 17 : 0 : 0 : No : No : : 7 : 7 : 16 : 0 : 0 : No : No : : 8 : 7 : 15 : 0 : 0 : No : No : : 9 : 5 : 9 : 0 : 0 : No : No : : 10 : 7 : 14 : 0 : 0 : No : No : : 11 : 3 : 8 : 27654 : 1 : Yes : No : : 12 : 13 : 13 : 0 : 0 : No : No : : 13 : 1 : 7 : 27654 : 4 : Yes : No : : 14 : 11 : 12 : 0 : 0 : No : No : : 15 : 0 : 6 : 51 : 1 : Yes : No : : 16 : 9 : 11 : 0 : 0 : No : No : : 17 : 0 : 5 : 51 : 1 : Yes : No : ------------------------------------------------------------------ Where: ID=response queue number Channel=channel number associated with the response Serial=serial number associated with the response Length=the number of bytes received so far Frames=the number of frames received so far Complete=is the response complete (Yes or No) Error=has an error occurred (Yes or No)
Next » Client Examples.
Copyright © 2000 Invisible Worlds. All Rights Reserved.
|
|||
|
