~justin-fathomdb/nova/justinsb-openstack-api-volumes

<?xml version="1.0" encoding="utf-8"?><!DOCTYPE html PUBLIC '-//W3C//DTD XHTML 1.0 Transitional//EN' 'http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd'><html lang="en" xmlns="http://www.w3.org/1999/xhtml">

<head>

<title>Twisted Documentation: Components: Interfaces and Adapters</title>

</head>

<h1 class="title">Components: Interfaces and Adapters</h1>

<div class="toc"><ol><li><a href="#auto0">Interfaces and Components in Twisted code</a></li><ul><li><a href="#auto1">Components and Inheritance</a></li></ul></ol></div>

Object oriented programming languages allow programmers to reuse portions of

existing code by creating new <q>classes</q> of objects which subclass another

class. When a class subclasses another, it is said to inherit all of its

behaviour. The subclass can then <q>override</q> and <q>extend</q> the behavior

provided to it by the superclass. Inheritance is very useful in many situations,

but because it is so convenient to use, often becomes abused in large software

systems, especially when multiple inheritance is involved. One solution is to

use delegation instead of <q>inheritance</q> where appropriate.

Delegation is simply the act of asking another object to perform a task

for an object. To support this design pattern, which is often referred to as the

components pattern because it involves many small interacting components,

interfaces and adapters were created by the Zope 3 team.

<q>Interfaces</q> are simply markers which objects can use to say <q>I

implement this interface</q>. Other objects may then make requests like

<q>Please give me an object which implements interface X for object type Y</q>.

Objects which implement an interface for another object type are called

<q>adapters</q>.

The superclass-subclass relationship is said to be an is-a relationship.

When designing object hierarchies, object modellers use subclassing when they

can say that the subclass is the same class as the superclass. For

example:

<pre class="python"> 1

class Shape:

sideLength = 0

def getSideLength(self):

return self.sideLength

def setSideLength(self, sideLength):

self.sideLength = sideLength

def area(self):

raise NotImplementedError, "Subclasses must implement area"

class Triangle(Shape):

def area(self):

return (self.sideLength * self.sideLength) / 2

class Square(Shape):

def area(self):

return self.sideLength * self.sideLength

</pre>

In the above example, a Triangle is-a Shape, so it subclasses Shape,

and a Square is-a Shape, so it also subclasses Shape.

However, subclassing can get complicated, especially when Multiple

Inheritance enters the picture. Multiple Inheritance allows a class to inherit

from more than one base class. Software which relies heavily on inheritance

often ends up having both very wide and very deep inheritance trees, meaning

that one class inherits from many superclasses spread throughout the system.

Since subclassing with Multiple Inheritance means implementation

inheritance, locating a method's actual implementation and ensuring the

correct method is actually being invoked becomes a challenge. For example:

<pre class="python"> 1

100

101

102

103

104

105

106

107

108

109

class Area:

110

sideLength = 0

111

def getSideLength(self):

112

return self.sideLength

113

114

def setSideLength(self, sideLength):

115

self.sideLength = sideLength

116

117

def area(self):

118

raise NotImplementedError, "Subclasses must implement area"

119

120

class Color:

121

color = None

122

def setColor(self, color):

123

self.color = color

124

125

def getColor(self):

126

return self.color

127

128

class Square(Area, Color):

129

def area(self):

130

131

</pre>

132

133

The reason programmers like using implementation inheritance is because it

134

makes code easier to read since the implementation details of Area are in a

135

separate place than the implementation details of Color. This is nice, because

136

conceivably an object could have a color but not an area, or an area but not a

137

color. The problem, though, is that Square is not really an Area or a Color, but

138

has an area and color. Thus, we should really be using another object oriented

139

technique called composition, which relies on delegation rather than

140

inheritance to break code into small reusable chunks. Let us continue with the

141

Multiple Inheritance example, though, because it is often used in practice.

142

143

What if both the Color and the Area base class defined the same method,

144

perhaps <code>calculate</code>? Where would the implementation come from? The

145

implementation that is located for <code>Square().calculate()</code> depends on

146

the method resolution order, or MRO, and can change when programmers change

147

seemingly unrelated things by refactoring classes in other parts of the system,

148

causing obscure bugs. Our first thought might be to change the calculate method

149

name to avoid name clashes, to perhaps <code>calculateArea</code> and

150

<code>calculateColor</code>. While explicit, this change could potentially

151

require a large number of changes throughout a system, and is error-prone,

152

especially when attempting to integrate two systems which you didn't write.

153

154

Let's imagine another example. We have an electric appliance, say a hair

155

dryer. The hair dryer is american voltage. We have two electric sockets, one of

156

them an american 110 Volt socket, and one of them a foreign 220 Volt socket. If

157

we plug the hair dryer into the 220 Volt socket, it is going to expect 110 Volt

158

current and errors will result. Going back and changing the hair dryer to

159

support both <code>plug110Volt</code> and <code>plug220Volt</code> methods would

160

be tedious, and what if we decided we needed to plug the hair dryer into yet

161

another type of socket? For example:

162

163

<pre class="python"> 1

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

class HairDryer:

179

def plug(self, socket):

180

if socket.voltage() == 110:

181

print "I was plugged in properly and am operating."

182

else:

183

print "I was plugged in improperly and "

184

print "now you have no hair dryer any more."

185

186

class AmericanSocket:

187

def voltage(self):

188

return 110

189

190

class ForeignSocket:

191

def voltage(self):

192

return 220

193

</pre>

194

195

Given these classes, the following operations can be performed:

196

197

198

>>> hd = HairDryer()

199

>>> am = AmericanSocket()

200

>>> hd.plug(am)

201

I was plugged in properly and am operating.

202

>>> fs = ForeignSocket()

203

>>> hd.plug(fs)

204

I was plugged in improperly and

205

now you have no hair dryer any more.

206

</pre>

207

208

We are going to attempt to solve this problem by writing an Adapter for the

209

<code>ForeignSocket</code> which converts the voltage for use with an American

210

hair dryer. An Adapter is a class which is constructed with one and only one

211

argument, the <q>adaptee</q> or <q>original</q> object. In this example, we

212

will show all code involved for clarity:

213

214

<pre class="python">1

215

216

217

218

219

220

class AdaptToAmericanSocket:

221

def __init__(self, original):

222

self.original = original

223

224

def voltage(self):

225

return self.original.voltage() / 2

226

</pre>

227

228

Now, we can use it as so:

229

230

231

>>> hd = HairDryer()

232

>>> fs = ForeignSocket()

233

>>> adapted = AdaptToAmericanSocket(fs)

234

>>> hd.plug(adapted)

235

I was plugged in properly and am operating.

236

</pre>

237

238

So, as you can see, an adapter can 'override' the original implementation. It

239

can also 'extend' the interface of the original object by providing methods the

240

original object did not have. Note that an Adapter must explicitly delegate any

241

method calls it does not wish to modify to the original, otherwise the Adapter

242

cannot be used in places where the original is expected. Usually this is not a

243

problem, as an Adapter is created to conform an object to a particular interface

244

and then discarded.

245

246

<h2>Interfaces and Components in Twisted code<a name="auto0"/></h2>

247

248

Adapters are a useful way of using multiple classes to factor code into

249

discrete chunks. However, they are not very interesting without some more

250

infrastructure. If each piece of code which wished to use an adapted object had

251

to explicitly construct the adapter itself, the coupling between components

252

would be too tight. We would like to achieve <q>loose coupling</q>, and this is

253

where <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.python.components.html" title="twisted.python.components">twisted.python.components</a></code> comes in.

254

255

First, we need to discuss Interfaces in more detail. As we mentioned

256

earlier, an Interface is nothing more than a class which is used as a marker.

257

Interfaces should be subclasses of <code>zope.interface.Interface</code>, and

258

have a very odd look to python programmers not used to them:

259

260

<pre class="python">1

261

262

263

264

265

266

from zope.interface import Interface

267

268

class IAmericanSocket(Interface):

269

def voltage():

270

"""Return the voltage produced by this socket object, as an integer.

271

"""

272

</pre>

273

274

Notice how it looks just like a regular class definition, other than

275

inheriting from <code>Interface</code>? However, the method definitions inside

276

the class block do not have any method body! Since Python does not have any

277

native language-level support for Interfaces like Java does, this is what

278

distinguishes an Interface definition from a Class.

279

280

Now that we have a defined Interface, we can talk about objects using terms

281

like this: <q>The <code>AmericanSocket</code> class implements the

282

<code>IAmericanSocket</code> interface</q> and <q>Please give me an object which

283

adapts <code>ForeignSocket</code> to the <code>IAmericanSocket</code>

284

interface</q>. We can make declarations about what interfaces a certain

285

class implements, and we can request adapters which implement a certain

286

interface for a specific class.

287

288

Let's look at how we declare that a class implements an interface:

289

290

<pre class="python">1

291

292

293

294

295

296

297

298

299

300

class AmericanSocket:

301

302

implements(IAmericanSocket)

303

304

def voltage(self):

305

return 110

306

</pre>

307

308

So, to declare that a class implements an interface, we simply call

309

<code>zope.interface.implements</code> at the class level.

310

311

Now, let's say we want to rewrite the <code>AdaptToAmericanSocket</code>

312

class as a real adapter. In this case we also specify it as implementing

313

<code>IAmericanSocket</code>:

314

315

<pre class="python"> 1

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

class AdaptToAmericanSocket:

332

333

implements(IAmericanSocket)

334

335

def __init__(self, original):

336

"""

337

Pass the original ForeignSocket object as original

338

"""

339

self.original = original

340

341

def voltage(self):

342

343

</pre>

344

345

Notice how we placed the implements declaration on this adapter class. So

346

far, we have not achieved anything by using components other than requiring us

347

to type more. In order for components to be useful, we must use the

348

component registry. Since <code>AdaptToAmericanSocket</code> implements

349

<code>IAmericanSocket</code> and regulates the voltage of a

350

<code>ForeignSocket</code> object, we can register

351

<code>AdaptToAmericanSocket</code> as an <code>IAmericanSocket</code> adapter

352

for the <code>ForeignSocket</code> class. It is easier to see how this is

353

done in code than to describe it:

354

355

<pre class="python"> 1

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

from twisted.python import components

389

390

class IAmericanSocket(Interface):

391

def voltage():

392

"""Return the voltage produced by this socket object, as an integer.

393

"""

394

395

class AmericanSocket:

396

implements(IAmericanSocket)

397

398

def voltage(self):

399

return 110

400

401

class ForeignSocket:

402

def voltage(self):

403

return 220

404

405

class AdaptToAmericanSocket:

406

407

implements(IAmericanSocket)

408

409

def __init__(self, original):

410

self.original = original

411

412

def voltage(self):

413

414

415

components.registerAdapter(

416

AdaptToAmericanSocket,

417

ForeignSocket,

418

IAmericanSocket)

419

</pre>

420

421

Now, if we run this script in the interactive interpreter, we can discover a

422

little more about how to use components. The first thing we can do is discover

423

whether an object implements an interface or not:

424

425

426

>>> IAmericanSocket.implementedBy(AmericanSocket)

427

True

428

>>> IAmericanSocket.implementedBy(ForeignSocket)

429

False

430

>>> am = AmericanSocket()

431

>>> fs = ForeignSocket()

432

>>> IAmericanSocket.providedBy(am)

433

True

434

>>> IAmericanSocket.providedBy(fs)

435

False

436

</pre>

437

438

As you can see, the <code>AmericanSocket</code> instance claims to

439

implement <code>IAmericanSocket</code>, but the <code>ForeignSocket</code>

440

does not. If we wanted to use the <code>HairDryer</code> with the

441

<code>AmericanSocket</code>, we could know that it would be safe to do so by

442

checking whether it implements <code>IAmericanSocket</code>. However, if we

443

decide we want to use <code>HairDryer</code> with a <code>ForeignSocket</code>

444

instance, we must adapt it to <code>IAmericanSocket</code> before

445

doing so. We use the interface object to do this:

446

447

448

>>> IAmericanSocket(fs)

449

<__main__.AdaptToAmericanSocket instance at 0x1a5120>

450

</pre>

451

452

When calling an interface with an object as an argument, the interface

453

looks in the adapter registry for an adapter which implements the interface for

454

the given instance's class. If it finds one, it constructs an instance of the

455

Adapter class, passing the constructor the original instance, and returns it.

456

Now the <code>HairDryer</code> can safely be used with the adapted

457

<code>ForeignSocket</code>. But what happens if we attempt to adapt an object

458

which already implements <code>IAmericanSocket</code>? We simply get back the

459

original instance:

460

461

462

>>> IAmericanSocket(am)

463

<__main__.AmericanSocket instance at 0x36bff0>

464

</pre>

465

466

So, we could write a new <q>smart</q> <code>HairDryer</code> which

467

automatically looked up an adapter for the socket you tried to plug it into:

468

469

<pre class="python">1

470

471

472

473

474

class HairDryer:

475

def plug(self, socket):

476

adapted = IAmericanSocket(socket)

477

assert adapted.voltage() == 110, "BOOM"

478

print "I was plugged in properly and am operating"

479

</pre>

480

481

Now, if we create an instance of our new <q>smart</q> <code>HairDryer</code>

482

and attempt to plug it in to various sockets, the <code>HairDryer</code> will

483

adapt itself automatically depending on the type of socket it is plugged in

484

to:

485

486

487

>>> am = AmericanSocket()

488

>>> fs = ForeignSocket()

489

>>> hd = HairDryer()

490

>>> hd.plug(am)

491

I was plugged in properly and am operating

492

>>> hd.plug(fs)

493

I was plugged in properly and am operating

494

</pre>

495

496

Voila; the magic of components.

497

498

<h3>Components and Inheritance<a name="auto1"/></h3>

499

500

If you inherit from a class which implements some interface, and your new

501

subclass declares that it implements another interface, the implements will be

502

inherited by default.

503

504

For example, <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.Root.html" title="twisted.spread.pb.Root">pb.Root</a></code> is a class

505

which implements <code class="API"><a href="http://twistedmatrix.com/documents/10.0.0/api/twisted.spread.pb.IPBRoot.html" title="twisted.spread.pb.IPBRoot">IPBRoot</a></code>. This interface indicates that an

506

object has remotely-invokable methods and can be used as the initial object

507

served by a new Broker instance. It has an <code>implements</code> setting

508

like:

509

510

<pre class="python">1

511

512

513

514

515

516

class Root(Referenceable):

517

implements(IPBRoot)

518

</pre>

519

520

Suppose you have your own class which implements your

521

<code>IMyInterface</code> interface:

522

523

<pre class="python">1

524

525

526

527

528

529

530

531

532

class IMyInterface(Interface):

533

pass

534

535

class MyThing:

536

implements(IMyInterface)

537

</pre>

538

539

Now if you want to make this class inherit from <code>pb.Root</code>,

540

the interfaces code will automatically determine that it also implements

541

<code>IPBRoot</code>:

542

543

<pre class="python">1

544

545

546

547

548

549

550

551

from twisted.spread import pb

552

from zope.interface import implements, Interface

553

554

class IMyInterface(Interface):

555

pass

556

557

class MyThing(pb.Root):

558

implements(IMyInterface)

559

</pre>

560

561

562

>>> from twisted.spread.flavors import IPBRoot

563

>>> IPBRoot.implementedBy(MyThing)

564

True

565

</pre>

566

567

If you want <code>MyThing</code> to inherit from <code>pb.Root</code> but

568

not implement <code>IPBRoot</code> like <code>pb.Root</code> does,

569

use <code>implementOnly</code>:

570

571

<pre class="python">1

572

573

574

575

576

577

578

579

580

from zope.interface import implementsOnly, Interface

581

582

class IMyInterface(Interface):

583

pass

584

585

class MyThing(pb.Root):

586

implementsOnly(IMyInterface)

587

</pre>

588

589

590

>>> from twisted.spread.pb import IPBRoot

591

>>> IPBRoot.implementedBy(MyThing)

592

False

593

</pre>

594

595

</div>

596

597

<a href="index.html">Index</a>

598

Version: 10.0.0

599

</body>

600

</html>

b'\\ No newline at end of file'

Older »