Adun  0.83
 All Classes Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Public Member Functions | Static Public Member Functions
ULServerManager Class Reference

#import <ULServerManager.h>

List of all members.

Public Member Functions

(id) - serverOnHost:
(id) - serverOnLocalhost
(BOOL) - checkForServerOnHost:
(void) - disconnectFromServer:
(void) - disconnectFromServerOnHost:
(void) - applicationWillClose
(NSDictionary *) - connectionErrors
(NSError *) - connectionErrorForHost:
(NSArray *) - connectedHosts
(NSArray *) - allServers
(NSArray *) - knownHosts
(BOOL) - isKnownHost:
(void) - addHost:
(void) - addHost:hostPort:
(void) - addHost:serverName:
(void) - addHost:persistant:connectNow:
(void) - addHost:hostPort:serverName:persistant:connectNow:
(ULRemoteMessageErrorCode- handleMessageException:fromHost:error:

Static Public Member Functions

(id) + appServerManager

Detailed Description


ULServerManager is a singleton class that creates and manages connections to AdunServer daemons. Primary attributes

ULServerManager follows a rigorous protocol for setting-up and shutting down connections and for handling connection errors. Objects obtaining connections to remote servers should use this object and observe the relevant notifications.

Setting Up a Connection

Before a connection can be made to a remote server, the host the server is running on must be a known host (i.e. in the array returned by knownHosts (ULServerManager)). If not it can be added using addHost: (ULServerManager) or a related method. Once a host is known, a connection is made on the first call to serverOnHost: (ULServerManager).

If the connection attempt is unsuccessful an NSError object describing the failure is created which can be accessed via connectionErrorForHost: (ULServerManager). See Error Descriptions for more information.

Shutting Down a Connection

Connections to remote hosts can be deliberately closed using disconnectFromServerOnHost: (ULServerManager). This should be done with care as other objects may be using the connection. Normally ULServerManager will perform the disconnections itself when it is deallocated.

ULServerManager can post two notifications when disconnecting. The first is a ULRemoteObjectWillBecomeInvalidNotification (for each remote object vended by the connection). This allows other objects using objects from the remote host to handle their disappearence gracefully. This is followed by ULDidDisconnectFromServerNotication.

Handling Errors

There are two general classes of errors that can occur when communicating with remote servers.

Both error types will cause exceptions to be raised when sending a message to the problem host. In some cases the cause of the exception will already have been handled by ULServerManager, but in others, notably Network errors, they won't. Since these exceptions cannot be caught by ULServerManager objects sending messages to remote hosts should catch them and then inform ULServerManager - it can then take necessary action i.e. enter the Disconnection Protocol. You inform the server by sending handleMessageException:fromHost:error: (ULServerManager).

Note: If you are unable to determine which host the remote object was from you can still call handleMessageException:fromHost:error: (ULServerManager).

Disconnection Protocol

ULServerManager proceeds through the following steps on detecting an unexpected disconnection event from a remote host. The disconnection can be detected automatically or via handleMessageException:fromHost:error: (ULServerManager) being called.

  1. ULRemoteObjectWillBecomeInvalidNotification's will be broadcast for every remote object vended by the server. Any object obtaining remote objects via this class should register for this notification.
  2. A ULDidDisconnectFromServerNotication is posted.
  3. A timer is set for a reconnection attempt to host.

An NSError object describing the reason for entering the protocol g it is always set for the disconnected host.

Error Descriptions

When an error with a connection is detected by the server an NSError object describing it can be obtained using connectionErrors (ULServerManager) or connectionErrorForHost: (ULServerManager). Errors are created when

Any previous errors regarding a connection to a host are removed when it is succesfully connected to.


If the AddPublishedServer default is YES ULServerManager will connect to servers that have published themselves on the LAN in addition to those specified in the list of persistant hosts. Note: The corresponding hosts are not added to the list of persistant hosts When ULServerManager connects to a published server it sends ULDidAddPublishedServerNotification When it disconnects from such a published server the normal disconnection protocol is entered.

Note: If a server is added persistantly and it also publishes itself it will not trigger ULDidAddPublishedServerNotifications. Therefore any objects that monitor the addition of published servers in order to automatically access their resources (e.g. databases) will not add anything if the server is persistant.


Member Function Documentation

- (void) addHost: (NSHost*)  host

Permanently adds a host to the known hosts. The receiver does not try to connect to the host. To connect use serverOnHost:

- (void) addHost: (NSHost*)  host
hostPort: (unsigned int)  port 

Use to create a non-persistant connection to a remote host via an explicit port. Note: The host can be anywhere in the world.

This method is the same as addHost:hostPort:serverName:persistant:connectNow: passing port for the port number, nil for the serverName and NO for persistant and connectNow.

- (void) addHost: (NSHost*)  host
hostPort: (unsigned int)  hostPort
serverName: (NSString*)  name
persistant: (BOOL)  persistant
connectNow: (BOOL)  connectNow 

Adds a host to the known hosts. If the host has already by added (even under a different name) this method does nothing. If hostPort and is greater 0 the host will be connected to using this port number. Otherwise serverName is the name used to find the server using a name-server. If serverName is nil then then AdunServer is used.

If persistant is YES the host is permantely added to the known hosts list. If connectNow is YES the receiver immediately attempts to connect to the host. If connectNow is YES the success of the connection attempt can be checked via connectionErrorForHost:.

Raises an NSInvalidArgumentException if host is nil or if it does not represent a real network location i.e. [host address] is nil.

- (void) addHost: (NSHost*)  host
persistant: (BOOL)  persistant
connectNow: (BOOL)  connectNow 

Use to create a connection to a host using the registeredName AdunServer. Note: This method only works if host is on the LAN.

As addHost:hostPort:serverName:persistant:connectNow: passing 0 for the port and nil for the name.

- (void) addHost: (NSHost*)  host
serverName: (NSString*)  name 

Use to create a non-persistant connection to a remote host via name servers. Note: This method only works if host is on the LAN.

This method is the same as addHost:hostPort:serverName:persistant:connectNow: passing name for the serverName, 0 for the port number and NO for persistant and connectNow.

- (NSArray *) allServers

Returns an array containing all the servers of all active connections If any of the servers cannot be retrieved the Disconnection Protocol is enetered for it before this method returns.

- (void) applicationWillClose

Causes the receiver to disconnect from all servers and invalidate all reconnection timers. This method should be called on exit of any program using ULServerManager to ensure all sockets associated with connections are released and all NSConnections on remote servers are released.

+ (id) appServerManager

Returns the default server manager

- (BOOL) checkForServerOnHost: (NSHost*)  host

Checks if a server is runing on host. Only works if the host is on a local network. Use connectedHosts to check who is currently connected.

- (NSArray*) connectedHosts

Returns an array of NSHost instances for the sucessfully contacted hosts

- (NSError *) connectionErrorForHost: (NSHost*)  host

If there is an error with the connection to host this method returns it. If there is no error it returns nil. If host is not in the array returned by knownHosts this method raises an NSInvalidArgumentException.

- (NSDictionary*) connectionErrors

Returns an dictionary whose keys are hostnames the receiver can not connect to and whose values are error object describing the reason for the problem.

- (void) disconnectFromServer: (id)  server

Closes the connection to the host vending server. Posts an ULInvalidatedServerConnectionNotification

- (void) disconnectFromServerOnHost: (NSHost*)  host

Closes the connection to the server on host hostname. Raises an ULUnknownHostException if hostname is not a known host. Note if the server is invalid this method does nothing.

ULRemoteObjectWillBecomeInvalidNotification will be posted for each object vended by the connection.

Note: Calling this method does not result in the Disconnection Protocol being entered.

- (ULRemoteMessageErrorCode) handleMessageException: (NSException*)  exception
fromHost: (NSHost*)  host
error: (NSError**)  error 

Handles exception which was raised when sending a remote message to hostname and returns information explaining what caused it. Depending on the exception the Disconnection Protocol may be entered.

For valid exceptions this method returns a code which describes reason for the failure - See ULRemoteMessageErrorCode. In addition if error is not NULL it contains an NSError object explaining the reason for the exception. If exception is not a recognised remote message ULErrorNotRecognized is returned and error is not set.

If exception is recoginized, and the cause is not ULNetworkTimeoutError or ULUnknownMessageExceptionCause, all connections are checked. If any are invalid the Disconnection Protocol is entered.

host may be nil since it may not be known by the sender of this message. For exceptions caused by invalid ports this has no effect since the host that raised the exception can be determined by the receiver. However for other error causes this is not possible. In these cases if the host is provided the error is associated with it and connectionErrorForHost: will return this value. Otherwise no host is associated with the error and connectionErrorForHost: will return nil. If hostname does not refer to a known host it is ignored.

Error Descriptions

The NSError obejct returned by this method and by a subsequent call to connectionErrorForHost: may differ for three reasons.

- (BOOL) isKnownHost: (NSHost*)  host

Returns YES if host is a known host.

- (NSArray*) knownHosts

Returns an array of NSHost objects representing all the hosts that the receiver tries to connect to.

- (id) serverOnHost: (NSHost*)  host

Returns the proxy for the AdunServer running on host or nil if the host could not be connected to. Raises an ULUnknownHostException if hostname is not a known host.

If a connection was not previously established a connection attempt is made. If the connection to hostname is invalid a reconnection attempt is made. If a nil connection is returned an NSError object describing the reason for the failure can be obtained using connectionErrorForHost:.

No notifications are sent directly by this method, however it is undefined if NSConnectionDidDieNotification will be posted if a existing connection is found to be invalid.

- (id) serverOnLocalhost

Returns the server on the local host if there is one