Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD

com.nexaweb.client.netservice
Interface NetService

All Known Subinterfaces:
DesktopNetService
public interface NetService

NetService provides methods for sending and receiving HTTP messages, subcribing and unsubcribing to message topics, and other network related functions.

Method Summary
 void closePushConnection()
          Closes the current push connection.
 java.net.URL createFullyQualifiedUrl(java.lang.String url)
          Creates a full url based on current context information.
 java.net.URL createFullyQualifiedUrl(java.lang.String baseUrl, java.lang.String url)
          Creates a fully qualified URL out of a base url and a relative url.
 java.net.URL createFullyQualifiedUrl(java.lang.String baseUrl, java.lang.String applicationPath, java.lang.String url, boolean keepContextPath)
          Creates a fully qualified URL out of a base url, an optional applicationPath and a relative url.
 HttpRequest createHttpRequest(java.lang.String url)
          Creates an HTTP request that can then be sent to the server.
 java.net.URL getServerUrl()
          Returns something like "http://localhost:8080
 void openBrowser(java.lang.String url)
          Opens a browser window with the given url.
 void openBrowser(java.lang.String url, java.lang.String target)
          Opens a browser window with the given url in the specified target frame.
 void openPushConnection()
          Opens the push connection.
 void publish(java.lang.String topic, byte[] content)
          Publishes a byte[] on the given topic.
 void publish(java.lang.String topic, Document content)
          Publishes a Document on the given topic.
 void publish(java.lang.String topic, Element content)
          Publishes an Element on the given topic.
 void publish(java.lang.String topic, java.io.Serializable content)
          Publishes a Serializable object on the given topic.
 void publish(java.lang.String topic, java.lang.String content)
          Publishes a String on the given topic.
 void publish(java.lang.String topic, XmlSerializable content)
          Publishes a XmlSerializable object on the given topic.
 HttpResponse retrieve(HttpRequest request)
          Gets a response from a url by making a request based on the input HttpRequest object.
 HttpResponse retrieve(java.lang.String url)
          Gets an HttpResponse object from the provided string url.
 HttpResponse retrieveAndProcess(HttpRequest request)
          Sends the the given request - the response is assumed to be XML and is parsed automatically by the client.
 HttpResponse retrieveAndProcess(java.lang.String url)
          Sends to the given url - the response is assumed to be in XML format and is processed automatically by the client.
 void retrieveAndProcessAsynchronously(HttpRequest request, NetServiceListener listener)
          Asynchronously sends the the given request - the response is assumed to be XML and is parsed automatically by the client.
 void retrieveAndProcessAsynchronously(java.lang.String url, NetServiceListener listener)
          Asynchronously sends to the given url - the response is assumed to be in XML format and will be processed automatically by the client.
 void retrieveAsynchronously(HttpRequest request, NetServiceListener listener)
          Asynchronously gets a response from an url by making a request based on the input HttpRequest object.
 void retrieveAsynchronously(java.lang.String url, NetServiceListener listener)
          Asynchronously gets an HttpResponse object from the provided string url.
 void startPolling()
          Starts a polling thread where client will send periodic request to the Nexaweb servlet.
 void stopPolling()
          Stops the current polling thread.
 void subscribe(java.lang.String[] topics, MessageListener listener)
          Subscribes to a set of topics.
 void subscribe(java.lang.String topic, MessageListener listener)
          Subscribes to a topic.
 void synchronize()
          Synchronize data with the server.
 void unsubscribe(java.lang.String topic)
          Unsubscribes a topic for all listeners.
 void unsubscribe(java.lang.String topic, MessageListener listener)
          Unsubscribes a topic for one listener.
 

Method Detail

openBrowser

public void openBrowser(java.lang.String url)
                 throws java.net.MalformedURLException
Opens a browser window with the given url.

Throws:
java.net.MalformedURLException

openBrowser

public void openBrowser(java.lang.String url,
                        java.lang.String target)
                 throws java.net.MalformedURLException
Opens a browser window with the given url in the specified target frame.

Parameters:
url - A full url or partial url relative to current server and application
target - The name of the frame/window to open the url in.
  • "_self" - Show in the window and frame that contain the applet.
  • "_parent" - Show in the applet's parent frame. If the applet's frame has no parent frame, acts the same as "_self".
    • "_top" - Show in the top-level frame of the applet's window. If the applet's frame is the top-level frame, acts the same as "_self".
  • "_blank" - Show in a new, unnamed top-level window.
  • other - Show in the frame or window named name. If a target named name does not already exist, a new top-level window with the specified name is created, and the document is shown there.
Throws:
java.net.MalformedURLException

getServerUrl

public java.net.URL getServerUrl()
Returns something like "http://localhost:8080

createFullyQualifiedUrl

public java.net.URL createFullyQualifiedUrl(java.lang.String url)
                                     throws java.net.MalformedURLException
Creates a full url based on current context information.

If the URL begins with "/", this is relative to the application root. If it does not start with "/", it is relative to the current application context. If the url starts with "http" it is returned as is.

Returns:
A fully qualfied URL
Throws:
java.net.MalformedURLException - if the string passed in is null or a bad url string

createFullyQualifiedUrl

public java.net.URL createFullyQualifiedUrl(java.lang.String baseUrl,
                                            java.lang.String url)
                                     throws java.net.MalformedURLException
Creates a fully qualified URL out of a base url and a relative url. This is intended primarily to help resolve relative URLs that are imbedded in other files.

If the url begins with "/", this is relative to the application root.

Parameters:
baseUrl - Something like http://localhost:8080/myApp/pages/
url - Something like ../myimages/myImage.gif
Returns:
The fully qualified URL
Throws:
java.net.MalformedURLException

createFullyQualifiedUrl

public java.net.URL createFullyQualifiedUrl(java.lang.String baseUrl,
                                            java.lang.String applicationPath,
                                            java.lang.String url,
                                            boolean keepContextPath)
                                     throws java.net.MalformedURLException
Creates a fully qualified URL out of a base url, an optional applicationPath and a relative url. This is intended primarily to help resolve relative URLs that are imbedded in other files.

Parameters:
baseUrl - Something like http://localhost:8080/myApp/path/pages, ending slash is needed if it's only a path.
url - Something like ../myimages/myImage.gif
keepContextPath - if this is false and url has leading slash, the contextPath will come from url parameter
Throws:
java.net.MalformedURLException

createHttpRequest

public HttpRequest createHttpRequest(java.lang.String url)
Creates an HTTP request that can then be sent to the server.

Parameters:
url - The url to the server page. This follows the rules of createFullyQualifiedUrl. If the url doesn't have a leading slash, the current application context will be used.

retrieveAndProcess

public HttpResponse retrieveAndProcess(java.lang.String url)
                                throws NetServiceException
Sends to the given url - the response is assumed to be in XML format and is processed automatically by the client.

Note the given url must be relative to the current application's context path. This is a server-side requirement.

Returns:
an HttpResponse object containing the retrieved data
Throws:
NetServiceException, - a wrapper exception of either a failed network call or a failed response processing. Check the getCausalThrowable() and printStackTrace() method to find out details.

The network cause could be MalformedURLException, FileNotFoundException, ConnectionException, IOException etc.

MalformedURLException: when a URL object can't be formed from the input url. This exception extends IOException and should be caught earlier than IOException.

FileNotFoundException: when the server side page can't be found or server returns http 404 status code. Note: Not all the JVM can detect server throws a 404 error. Sometimes, 404 error falls to 500 or IOException error. This exception extends IOException and should be caught earlier than IOException. If the url is in the classpath:// format or loading context, this exception means loading this resource returns null.

ConnectException: when the server is not reacheable. Note: Not all the JVM can detect server throws a ConnectException error. Sometimes, this error falls to 500 or IOException error. This exception extends IOException and should be caught earlier than IOException.

IOException: when the server side page can't be found or server returns http 404 status code. Note: Not all the JVM can detect server throws a 404 error. Sometimes, 404 error falls to 500 or IOException error. This exception extends IOException and should be caught earlier than IOException.

The process cause could be ParserException etc.

com.nexaweb.xml.ParserException: when the data contains a malformed XML; however, any XML up to the point of malformed data will be processed and executed. Also note that a well-formed but non-relevant XML, will be ignored during the processing and will not trigger an exception.

NetServiceException

retrieveAndProcessAsynchronously

public void retrieveAndProcessAsynchronously(java.lang.String url,
                                             NetServiceListener listener)
Asynchronously sends to the given url - the response is assumed to be in XML format and will be processed automatically by the client.

Note the given url must be relative to the current application's context path. This is a server-side requirement.

Parameters:
url - The destination url relative to the application context path.
listener - The listener to asynchronously call back when the retrieve is finished or an error occurs.

retrieveAndProcess

public HttpResponse retrieveAndProcess(HttpRequest request)
                                throws NetServiceException
Sends the the given request - the response is assumed to be XML and is parsed automatically by the client. The body and headers specified in the request object are transferred to the server. This method blocks until the request has been processed.

Note the given url must be relative to the current application's context path. This is a server-side requirement.

Returns:
an HttpResponse object containing the retrieved data
Throws:
NetServiceException, - a wrapper exception of either a failed network call or a failed response processing. Check the getCausalThrowable() and printStackTrace() method to find out details.

The network cause could be MalformedURLException, FileNotFoundException, ConnectionException, IOException etc.

MalformedURLException: when a URL object can't be formed from the input url. This exception extends IOException and should be caught earlier than IOException.

FileNotFoundException: when the server side page can't be found or server returns http 404 status code. Note: Not all the JVM can detect server throws a 404 error. Sometimes, 404 error falls to 500 or IOException error. This exception extends IOException and should be caught earlier than IOException. If the url is in the classpath:// format or loading context, this exception means loading this resource returns null.

ConnectException: when the server is not reacheable. Note: Not all the JVM can detect server throws a ConnectException error. Sometimes, this error falls to 500 or IOException error. This exception extends IOException and should be caught earlier than IOException.

IOException: when the server side page can't be found or server returns http 404 status code. Note: Not all the JVM can detect server throws a 404 error. Sometimes, 404 error falls to 500 or IOException error. This exception extends IOException and should be caught earlier than IOException.

The process cause could be ParserException etc.

com.nexaweb.xml.ParserException: when the data contains a malformed XML; however, any XML up to the point of malformed data will be processed and executed. Also note that a well-formed but non-relevant XML, will be ignored during the processing and will not trigger an exception.

NetServiceException

retrieveAndProcessAsynchronously

public void retrieveAndProcessAsynchronously(HttpRequest request,
                                             NetServiceListener listener)
Asynchronously sends the the given request - the response is assumed to be XML and is parsed automatically by the client. The body and headers specified in the request object are transferred to the server.

Note the given url must be relative to the current application's context path. This is a server-side requirement.

retrieve

public HttpResponse retrieve(java.lang.String url)
                      throws NetServiceException
Gets an HttpResponse object from the provided string url.

Returns:
an HttpResponse object,object won't be null, but content might be null
Throws:
NetServiceException, - a wrapper exception. Check the getCause() method to find out details. The cause could be MalformedURLException, FileNotFoundException, ConnectionException, IOException.

MalformedURLException: when a URL object can't be formed from the input url. This exception extends IOException and should be caught earlier than IOException.

FileNotFoundException: when the server side page can't be found or server returns http 404 status code. Note: Not all the JVM can detect server throws a 404 error. Sometimes, 404 error falls to 500 or IOException error. This exception extends IOException and should be caught earlier than IOException. If the url is in the classpath:// format or loading context, this exception means loading this resource returns null.

ConnectException: when the server is not reacheable. Note: Not all the JVM can detect server throws a ConnectException error. Sometimes, this error falls to 500 or IOException error. This exception extends IOException and should be caught earlier than IOException.

IOException: when the server side page can't be found or server returns http 404 status code. Note: Not all the JVM can detect server throws a 404 error. Sometimes, 404 error falls to 500 or IOException error. This exception extends IOException and should be caught earlier than IOException.

NetServiceException

retrieveAsynchronously

public void retrieveAsynchronously(java.lang.String url,
                                   NetServiceListener listener)
Asynchronously gets an HttpResponse object from the provided string url.

Parameters:
listener - The listener to asynchronously call back when the retrieve is finished or an error occurs.

retrieve

public HttpResponse retrieve(HttpRequest request)
                      throws NetServiceException
Gets a response from a url by making a request based on the input HttpRequest object.

Returns:
an HttpResponse object, object won't be null, but content might be null
Throws:
NetServiceException, - a wrapper exception. Check the getCause() method to find out details. The cause could be MalformedURLException, FileNotFoundException, ConnectionException, IOException.

MalformedURLException: when a URL object can't be formed from the input url. This exception extends IOException and should be caught earlier than IOException.

FileNotFoundException: when the server side page can't be found or server returns http 404 status code. Note: Not all the JVM can detect server throws a 404 error. Sometimes, 404 error falls to 500 or IOException error. This exception extends IOException and should be caught earlier than IOException. If the url is in the classpath:// format or loading context, this exception means loading this resource returns null.

ConnectException: when the server is not reacheable. Note: Not all the JVM can detect server throws a ConnectException error. Sometimes, this error falls to 500 or IOException error. This exception extends IOException and should be caught earlier than IOException.

IOException: when the server side page can't be found or server returns http 404 status code. Note: Not all the JVM can detect server throws a 404 error. Sometimes, 404 error falls to 500 or IOException error. This exception extends IOException and should be caught earlier than IOException.

NetServiceException

retrieveAsynchronously

public void retrieveAsynchronously(HttpRequest request,
                                   NetServiceListener listener)
Asynchronously gets a response from an url by making a request based on the input HttpRequest object.

Parameters:
listener - The listener to asynchronously call back when the retrieve is finished or an error occurs.

synchronize

public void synchronize()
                 throws NetServiceException
Synchronize data with the server.

Throws:
NetServiceException

openPushConnection

public void openPushConnection()
                        throws java.net.ProtocolException,
                               NetServiceException
Opens the push connection.

This method will send a request to the server to establish the push connection. This method will block until the push connection is established.

Due to JVM's limitation, you should use only one push connection for a browser process. Using 2 push connections in one process will sometimes cause you not able to make further requests to the same server. This usually happens you have two browser windows from the same process and both have a push connection to the same server application. Opening a new browser window in the same process won't resolve the problem. You need to restart your browser.

Note some JVMs can't support push connection. Typically they are: 1. Netscape 4.x JVM with JDK 1.1.5 support

Throws:
java.net.ProtocolException - when a JVM is detected not supporting a push connection. There is not request sent to the server.
NetServiceException - when there is an exception when trying to establsh a push connection with the server.

closePushConnection

public void closePushConnection()
Closes the current push connection.

This method will send a close push connection request to the server and block until the connection is closed.

subscribe

public void subscribe(java.lang.String topic,
                      MessageListener listener)
               throws NetServiceException
Subscribes to a topic. This method blocks until the topic has been successfully subscribed to. User can subscribe multiple topics and/or subscribe one topic with multiple listeners by calling this method multiple times.

Parameters:
topic - The non-null name of the topic.
listener - The listener that will process the topic content.
Throws:
NetServiceException
java.lang.IllegalArgumentException - Thrown if the topic contains a '*', which is reserved for future use, or either the topic or the listener is null.

subscribe

public void subscribe(java.lang.String[] topics,
                      MessageListener listener)
               throws NetServiceException
Subscribes to a set of topics. This method blocks until all topics have been successfully subscribed to.

Parameters:
topics - The topic array.
listener - The listener that will process the topic content.
Throws:
NetServiceException
java.lang.IllegalArgumentException - Thrown if the topic contains a '*', which is reserved for future use, or either the topic or the listener is null.

unsubscribe

public void unsubscribe(java.lang.String topic)
                 throws NetServiceException
Unsubscribes a topic for all listeners. This method blocks until the topic has been successfully unsubscribed to.

Parameters:
topic - The non-null name of the topic.
Throws:
NetServiceException
java.lang.IllegalArgumentException - Thrown if the topic is null.

unsubscribe

public void unsubscribe(java.lang.String topic,
                        MessageListener listener)
                 throws NetServiceException
Unsubscribes a topic for one listener. This method blocks until the topic has been successfully unsubscribed to. The parameter is to be the original instance that's added by calling the subscribe method.

After removing one listener, if there are still other listerners for the same topic, the remaing listeners will continue to be notified when messages arrive.

Parameters:
topic - The non-null name of the topic.
listener - A listener instance
Throws:
NetServiceException
java.lang.IllegalArgumentException - Thrown if either the topic or the listener is null.

publish

public void publish(java.lang.String topic,
                    Document content)
             throws NetServiceException
Publishes a Document on the given topic. This method blocks until the publish is completed.

Parameters:
topic - The topic this message should be published on.
content - The Document to publish.
Throws:
NetServiceException

publish

public void publish(java.lang.String topic,
                    Element content)
             throws NetServiceException
Publishes an Element on the given topic. This method blocks until the publish is completed.

Parameters:
topic - The topic this message should be published on.
content - The Element to publish.
Throws:
NetServiceException

publish

public void publish(java.lang.String topic,
                    java.io.Serializable content)
             throws NetServiceException
Publishes a Serializable object on the given topic. This method blocks until the publish is completed.

Parameters:
topic - The topic this message should be published on.
content - The Serializable object to publish.
Throws:
NetServiceException

publish

public void publish(java.lang.String topic,
                    XmlSerializable content)
             throws NetServiceException
Publishes a XmlSerializable object on the given topic. This method blocks until the publish is completed.

Parameters:
topic - The topic this message should be published on.
content - The XmlSerializable object to publish.
Throws:
NetServiceException

publish

public void publish(java.lang.String topic,
                    byte[] content)
             throws NetServiceException
Publishes a byte[] on the given topic. This method blocks until the publish is completed.

Parameters:
topic - The topic this message should be published on.
content - The byte[] to publish.
Throws:
NetServiceException

publish

public void publish(java.lang.String topic,
                    java.lang.String content)
             throws NetServiceException
Publishes a String on the given topic. This method blocks until the publish is completed.

Parameters:
topic - The topic this message should be published on.
content - The String to publish.
Throws:
NetServiceException

startPolling

public void startPolling()
Starts a polling thread where client will send periodic request to the Nexaweb servlet. The polling interval is set through SessionConfig when the session is established. This method won't block.

stopPolling

public void stopPolling()
                 throws java.net.ProtocolException
Stops the current polling thread. This method won't block.

Throws:
java.net.ProtocolException - when reliable messaging is enabled, calling this method will throw ProtocolException.
Overview  Package   Class  Use  Tree  Deprecated  Index  Help 
 PREV CLASS   NEXT CLASS FRAMES    NO FRAMES    
SUMMARY: NESTED | FIELD | CONSTR | METHOD DETAIL: FIELD | CONSTR | METHOD
Copyright © 2005 Nexaweb Technologies, Inc. All Rights Reserved.