1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
|
//
// GTMTransientRootProxy.h
//
// Copyright 2006-2009 Google Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License"); you may not
// use this file except in compliance with the License. You may obtain a copy
// of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
// WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
// License for the specific language governing permissions and limitations under
// the License.
//
#import <Foundation/Foundation.h>
#import "GTMDefines.h"
// Handle (re-)connecting to a transient root proxy object via DO.
//
// This class is designed to handle connecting and reconnecting to a Distributed
// Objects root proxy (NSDistantObject* instance). It is a replacement for using
// the NSDistantObject returned from NSConnection, directly. When the DO
// connection is up, messages sent to this class are forwarded to the real
// object (the NSDistantObject); when the DO connection is down, messages sent
// to this class are silently swallowed. You can use the -isConnected method on
// this class to see if the DO connection is up or down.
//
// This class may be useful when you need a DO connection, but the
// server you're connected to may be going up and down. For example, the
// web browser plugins in Google Desktop may need to connect to the Google
// Desktop local webserver, but we'd want the browser plugins to be able to
// gracefully handle the local Google Desktop webserver starting and stopping.
//
// === Example Usage ===
//
// Old code:
//
// NSDistantObject<MyProto> *o =
// [NSConnection rootProxyForConnectionWithRegisteredName:@"server"
// host:nil];
// [o setProtocolForProxy:@protocol(MyProto)];
// [o someMethodInMyProto];
// // ... write a bunch of code to handle error conditions
//
// New code:
//
// GTMTransientRootProxy<MyProto> *o =
// [GTMTransientRootProxy rootProxyWithRegisteredName:@"server"
// host:nil
// protocol:@protocol(MyProto)
// requestTimeout:5.0
// replyTimeout:5.0];
// [o someMethodInMyProto];
//
// The 'Old code' requires you to handle all the error conditions that may
// arise when using DO (such as the server crashing, or network going down),
// handle properly tearing down the broken connection, and trying to reconnect
// when the server finally comes back online. The 'New code' handles all of
// those details for you.
//
// Also, when creating a GMTransientRootProxy object, you must tell it the
// @protocol that will be used for communication - this is not optional. And
// in order to quiet compiler warnings, you'll also want to staticly type
// the pointer with the protocol as well.
//
@interface GTMTransientRootProxy : NSProxy {
@protected
GTM_WEAK Protocol *protocol_;
NSDistantObject *realProxy_;
NSString *registeredName_;
NSString *host_;
NSTimeInterval requestTimeout_;
NSTimeInterval replyTimeout_;
}
// Returns an autoreleased instance
+ (id)rootProxyWithRegisteredName:(NSString *)name
host:(NSString *)host
protocol:(Protocol *)protocol
requestTimeout:(NSTimeInterval)requestTimeout
replyTimeout:(NSTimeInterval)replyTimeout;
// This function will return a GTMTransientRootProxy that is using Mach ports
// for the connection. The |name| and |host| arguments will be used to lookup
// the correct information to create the Mach port connection.
//
- (id)initWithRegisteredName:(NSString *)name
host:(NSString *)host
protocol:(Protocol *)protocol
requestTimeout:(NSTimeInterval)requestTimeout
replyTimeout:(NSTimeInterval)replyTimeout;
// Returns YES if the DO connection is up and working, NO otherwise.
//
- (BOOL)isConnected;
@end
// Subclass of GTMTransientRootProxy that catches and ignores ALL exceptions.
// This class overrides GTMTransientRootProxy's -forwardInvocation:
// method, and wraps it in a try/catch block, and ignores all exceptions.
//
@interface GTMRootProxyCatchAll : GTMTransientRootProxy
// Overridden, and ignores all thrown exceptions.
- (void)forwardInvocation:(NSInvocation *)invocation;
@end
|
