Let’s start by adding support to the GumballMachine class so that it can handle locations:

Now let’s create another class, GumballMonitor, that retrieves the machine’s location, inventory of gumballs, and current machine state and prints them in a nice little report:

We implemented that in no time. The CEO is going to be thrilled and amazed by our development skills.

Now we just need to instantiate a GumballMonitor and give it a machine to monitor:

Frank: A remote what?

Joe: Remote proxy. Think about it: we’ve already got the monitor code written, right? We give the GumballMonitor a reference to a machine and it gives us a report. The problem is that the monitor runs in the same JVM as the gumball machine and the CEO wants to sit at his desk and remotely monitor the machines! So what if we left our GumballMonitor class as is, but handed it a proxy to a remote object?

Frank: I’m not sure I get it.

Jim: Me neither.

Joe: Let’s start at the beginning... a proxy is a stand in for a real object. In this case, the proxy acts just like it is a Gumball Machine object, but behind the scenes it is communicating over the network to talk to the real, remote GumballMachine.

Jim: So you’re saying we keep our code as it is, and we give the monitor a reference to a proxy version of the GumballMachine...

Frank: And this proxy pretends it’s the real object, but it’s really just communicating over the net to the real object.

Joe: Yeah, that’s pretty much the story.

Frank: It sounds like something that is easier said than done.

Joe: Perhaps, but I don’t think it’ll be that bad. We have to make sure that the gumball machine can act as a service and accept requests over the network; we also need to give our monitor a way to get a reference to a proxy object, but we’ve got some great tools already built into Java to help us. Let’s talk a little more about remote proxies first...

A remote proxy acts as a local representative to a remote object. What’s a “remote object”? It’s an object that lives in the heap of a different Java Virtual Machine (or more generally, a remote object that is running in a different address space). What’s a “local representative”? It’s an object that you can call local methods on and have them forwarded on to the remote object.

On paper this looks good, but how do we create a proxy that knows how to invoke a method on an object that lives in another JVM?

Hmmm. Well, you can’t get a reference to something on another heap, right? In other words, you can’t say:

Duck d = <object in another heap>

Whatever the variable d is referencing must be in the same heap space as the code running the statement. So how do we approach this? Well, that’s where Java’s Remote Method Invocation comes in... RMI gives us a way to find objects in a remote JVM and allows us to invoke their methods.

You may have encountered RMI in Head First Java; if not, take a slight detour and get up to speed on RMI before adding the proxy support to the Gumball Machine code.

So, here’s what we’re going to do:

Let’s say we want to design a system that allows us to call a local object that forwards each request to a remote object. How would we design it? We’d need a couple of helper objects that actually do the communicating for us. The helpers make it possible for the client to act as though it’s calling a method on a local object (which in fact, it is). The client calls a method on the client helper, as if the client helper were the actual service. The client helper then takes care of forwarding that request for us.

In other words, the client object thinks it’s calling a method on the remote service, because the client helper is pretending to be the service object. Pretending to be the thing with the method the client wants to call.

But the client helper isn’t really the remote service. Although the client helper acts like it (because it has the same method that the service is advertising), the client helper doesn’t have any of the actual method logic the client is expecting. Instead, the client helper contacts the server, transfers information about the method call (e.g., name of the method, arguments, etc.), and waits for a return from the server.

On the server side, the service helper receives the request from the client helper (through a Socket connection), unpacks the information about the call, and then invokes the real method on the real service object. So, to the service object, the call is local. It’s coming from the service helper, not a remote client.

The service helper gets the return value from the service, packs it up, and ships it back (over a Socket’s output stream) to the client helper. The client helper unpacks the information and returns the value to the client object.

How the method call happens

Okay, you’ve got the gist of how remote methods work; now you just need to understand how to use RMI to enable remote method invocation.

What RMI does for you is build the client and service helper objects, right down to creating a client helper object with the same methods as the remote service. The nice thing about RMI is that you don’t have to write any of the networking or I/O code yourself. With your client, you call remote methods (i.e., the ones the Real Service has) just like normal method calls on objects running in the client’s own local JVM.

RMI also provides all the runtime infrastructure to make it all work, including a lookup service that the client can use to find and access the remote objects.

There is one difference between RMI calls and local (normal) method calls. Remember that even though to the client it looks like the method call is local, the client helper sends the method call across the network. So there is networking and I/O. And what do we know about networking and I/O methods?

They’re risky! They can fail! And so, they throw exceptions all over the place. As a result, the client does have to acknowledge the risk. We’ll see how in a few pages.

RMI Nomenclature: in RMI, the client helper is a ‘stub’ and the service helper is a ‘skeleton’.

Now let’s go through all the steps needed to make an object into a service that can accept remote calls and also the steps needed to allow a client to make remote calls.

You might want to make sure your seat belt is fastened; there are a lot of steps and a few bumps and curves—but nothing to be too worried about.

Making the Remote service

This is an overview of the five steps for making the remote service. In other words, the steps needed to take an ordinary object and supercharge it so it can be called by a remote client. We’ll be doing this later to our GumballMachine. For now, let’s get the steps down and then we’ll explain each one in detail.

Step one:

Step two:

Step three:

Step four:

Step one: make a Remote interface

Step two: make a Remote implementation

Step three: run rmiregistry

Step four: start the service

Complete code for the server side

The Remote interface:

The Remote service (the implementation):

The client has to get the stub object (our proxy), since that’s the thing the client will call methods on. And that’s where the RMI registry comes in. The client does a ‘lookup’, like going to the white pages of a phone book, and essentially says, “Here’s a name, and I’d like the stub that goes with that name.”

Let’s take a look at the code we need to look-up and retrieve a stub object.

Code Up Close

Note

Here’s how it works.

How it works...

Complete client code

Okay, now that you have the RMI basics down, you’ve got the tools you need to implement the gumball machine remote proxy. Let’s take a look at how the GumballMachine fits into this framework:

The first step in converting our code to use the remote proxy is to enable the GumballMachine to service remote requests from clients. In other words, we’re going to make it into a service. To do that, we need to:

We’ll start with the remote interface:

We have one return type that isn’t Serializable: the State class. Let’s fix it up...

Actually, we’re not done with Serializable yet; we have one problem with State. As you may remember, each State object maintains a reference to a gumball machine so that it can call the gumball machine’s methods and change its state. We don’t want the entire gumball machine serialized and transferred with the State object. There is an easy way to fix this:

We’ve already implemented our GumballMachine, but we need to make sure it can act as a service and handle requests coming from over the network. To do that, we have to make sure the GumballMachine is doing everything it needs to implement the GumballMachineRemote interface.

As you’ve already seen in the RMI detour, this is quite simple; all we need to do is add a couple of things...

That completes the gumball machine service. Now we just need to fire it up so it can receive requests. First, we need to make sure we register it with the RMI registry so that clients can locate it.

We’re going to add a little code to the test drive that will take care of this for us:

Let’s go ahead and get this running...

Remember the GumballMonitor? We wanted to reuse it without having to rewrite it to work over a network. Well, we’re pretty much going to do that, but we do need to make a few changes.

Now we’ve got all the pieces we need. We just need to write some code so the CEO can monitor a bunch of gumball machines:

Code Up Close

Okay, it’s time to put all this work together and give another demo. First let’s make sure a few gumball machines are running the new code:

And now let’s put the monitor in the hands of the CEO. Hopefully, this time he’ll love it

By invoking methods on the proxy, we make a remote call across the wire, and get back a String, an integer, and a State object. Because we are using a proxy, the GumballMonitor doesn’t know, or care, that calls are remote (other than having to worry about remote exceptions).

Behind the Scenes

• ① The CEO runs the monitor, which first grabs the proxies to the remote gumball machines and then calls getState() on each one (along with getCount() and getLocation()).

  

• ② getState() is called on the proxy, which forwards the call to the remote service. The skeleton receives the request and then forwards it to the gumball machine.

  

• ③ GumballMachine returns the state to the skeleton, which serializes it and transfers it back over the wire to the proxy. The proxy deserializes it and returns it as an object to the monitor.

  

Note

We also have a small bit of code to register and locate stubs using the RMI registry. But no matter what, if we were writing something to work over the Internet, we’d need some kind of locator service.

We’ve already put a lot of pages behind us in this chapter; as you can see, explaining the Remote Proxy is quite involved. Despite that, you’ll see that the definition and class diagram for the Proxy Pattern is actually fairly straightforward. Note that Remote Proxy is one implementation of the general Proxy Pattern; there are actually quite a few variations of the pattern, and we’ll talk about them later. For now, let’s get the details of the general pattern down.

Here’s the Proxy Pattern definition:

Well, we’ve seen how the Proxy Pattern provides a surrogate or placeholder for another object. We’ve also described the proxy as a “representative” for another object.

But what about a proxy controlling access? That sounds a little strange. No worries. In the case of the gumball machine, just think of the proxy controlling access to the remote object. The proxy needed to control access because our client, the monitor, didn’t know how to talk to a remote object. So in some sense the remote proxy controlled access so that it could handle the network details for us. As we just discussed, there are many variations of the Proxy Pattern, and the variations typically revolve around the way the proxy “controls access.” We’re going to talk more about this later, but for now here are a few ways proxies control access:

Now that you’ve got the gist of the general pattern, check out the class diagram...

Let’s step through the diagram...

First we have a Subject, which provides an interface for the RealSubject and the Proxy. By implementing the same interface, the Proxy can be substituted for the RealSubject anywhere it occurs.

The RealSubject is the object that does the real work. It’s the object that the Proxy represents and controls access to.

The Proxy holds a reference to the RealSubject. In some cases, the Proxy may be responsible for creating and destroying the RealSubject. Clients interact with the RealSubject through the Proxy. Because the Proxy and RealSubject implement the same interface (Subject), the Proxy can be substituted anywhere the subject can be used. The Proxy also controls access to the RealSubject; this control may be needed if the Subject is running on a remote machine, if the Subject is expensive to create in some way or if access to the subject needs to be protected in some way.

Now that you understand the general pattern, let’s look at some other ways of using proxy beyond the Remote Proxy...

Okay, so far you’ve seen the definition of the Proxy Pattern and you’ve taken a look at one specific example: the Remote Proxy. Now we’re going to take a look at a different type of proxy, the Virtual Proxy. As you’ll discover, the Proxy Pattern can manifest itself in many forms, yet all the forms follow roughly the general proxy design. Why so many forms? Because the Proxy Pattern can be applied to a lot of different use cases. Let’s check out the Virtual Proxy and compare it to Remote Proxy:

Remote Proxy

With Remote Proxy, the proxy acts as a local representative for an object that lives in a different JVM. A method call on the proxy results in the call being transferred over the wire, invoked remotely, and the result being returned back to the proxy and then to the Client.

Virtual Proxy

Virtual Proxy acts as a representative for an object that may be expensive to create. The Virtual Proxy often defers the creation of the object until it is needed; the Virtual Proxy also acts as a surrogate for the object before and while it is being created. After that, the proxy delegates requests directly to the RealSubject.

Let’s say you want to write an application that displays your favorite compact disc covers. You might create a menu of the CD titles and then retrieve the images from an online service like Amazon.com. If you’re using Swing, you might create an Icon and ask it to load the image from the network. The only problem is, depending on the network load and the bandwidth of your connection, retrieving a CD cover might take a little time, so your application should display something while you are waiting for the image to load. We also don’t want to hang up the entire application while it’s waiting on the image. Once the image is loaded, the message should go away and you should see the image.

An easy way to achieve this is through a virtual proxy. The virtual proxy can stand in place of the icon, manage the background loading, and before the image is fully retrieved from the network, display “Loading CD cover, please wait...”. Once the image is loaded, the proxy delegates the display to the Icon.

Before writing the code for the CD Cover Viewer, let’s look at the class diagram. You’ll see this looks just like our Remote Proxy class diagram, but here the proxy is used to hide an object that is expensive to create (because we need to retrieve the data for the Icon over the network) as opposed to an object that actually lives somewhere else on the network.

Java’s got its own proxy support right in the java.lang.reflect package. With this package, Java lets you create a proxy class on the fly that implements one or more interfaces and forwards method invocations to a class that you specify. Because the actual proxy class is created at runtime, we refer to this Java technology as a dynamic proxy.

We’re going to use Java’s dynamic proxy to create our next proxy implementation (a protection proxy), but before we do that, let’s quickly look at a class diagram that shows how dynamic proxies are put together. Like most things in the real world, it differs slightly from the classic definition of the pattern:

Because Java creates the Proxy class for you, you need a way to tell the Proxy class what to do. You can’t put that code into the Proxy class like we did before, because you’re not implementing one directly. So, if you can’t put this code in the Proxy class, where do you put it? In an InvocationHandler. The job of the InvocationHandler is to respond to any method calls on the proxy. Think of the InvocationHandler as the object the Proxy asks to do all the real work after it’s received the method calls.

Okay, let’s step through how to use the dynamic proxy...

Every town needs a matchmaking service, right? You’ve risen to the task and implemented a dating service for Objectville. You’ve also tried to be innovative by including a “Hot or Not” feature in the service where participants can rate each other—you figure this keeps your customers engaged and looking through possible matches; it also makes things a lot more fun.

Your service revolves around a PersonBean that allows you to set and get information about a person:

Now let’s check out the implementation...

While we suspect other factors may be keeping Elroy from getting dates, he is right: you shouldn’t be able to vote for yourself or to change another customer’s data. The way our PersonBean is defined, any client can call any of the methods.

This is a perfect example of where we might be able to use a Protection Proxy. What’s a Protection Proxy? It’s a proxy that controls access to an object based on access rights. For instance, if we had an employee object, a Protection Proxy might allow the employee to call certain methods on the object, a manager to call additional methods (like setSalary()), and a human resources employee to call any method on the object.

In our dating service we want to make sure that a customer can set his own information while preventing others from altering it. We also want to allow just the opposite with the HotOrNot ratings: we want the other customers to be able to set the rating, but not that particular customer. We also have a number of getter methods in the PersonBean, and because none of these return private information, any customer should be able to call them.

The Internet bubble seems a distant memory; those were the days when all you needed to do to find a better, higher-paying job was to walk across the street. Even agents for software developers were in vogue...

We have a couple of problems to fix: customers shouldn’t be changing their own HotOrNot rating and customers shouldn’t be able to change other customers’ personal information. To fix these problems we’re going to create two proxies: one for accessing your own PersonBean object and one for accessing another customer’s PersonBean object. That way, the proxies can control what requests can be made in each circumstance.

To create these proxies we’re going to use the Java API’s dynamic proxy that you saw a few pages back. Java will create two proxies for us; all we need to do is supply the handlers that know what to do when a method is invoked on the proxy.

Step one:

Step two:

Step three:

We know we need to write two invocation handlers, one for the owner and one for the non-owner. But what are invocation handlers? Here’s the way to think about them: when a method call is made on the proxy, the proxy forwards that call to your invocation handler, but not by calling the invocation handler’s corresponding method. So, what does it call? Have a look at the InvocationHandler interface:

There’s only one method, invoke(), and no matter what methods get called on the proxy, the invoke() method is what gets called on the handler. Let’s see how this works:

When invoke() is called by the proxy, how do you know what to do with the call? Typically, you’ll examine the method that was called on the proxy and make decisions based on the method’s name and possibly its arguments. Let’s implement the OwnerInvocationHandler to see how this works:

Now, all we have left is to dynamically create the Proxy class and instantiate the proxy object. Let’s start by writing a method that takes a PersonBean and knows how to create an owner proxy for it. That is, we’re going to create the kind of proxy that forwards its method calls to the OwnerInvocationHandler. Here’s the code:

Let’s give the matchmaking service a test run and see how it controls access to the setter methods based on the proxy that is used.

Welcome to the Objectville Zoo!

You now know about the remote, virtual and protection proxies, but out in the wild you’re going to see lots of mutations of this pattern. Over here in the Proxy corner of the zoo we’ve got a nice collection of wild proxy patterns that we’ve captured for your study.

Our job isn’t done; we are sure you’re going to see more variations of this pattern in the real world, so give us a hand in cataloging more proxies. Let’s take a look at the existing collection:

____________________________________________________

____________________________________________________

____________________________________________________

____________________________________________________

____________________________________________________

Design Patterns Crossword

It’s been a LONG chapter. Why not unwind by doing a crossword puzzle before it ends?

Across

Down

1. Our first mistake: the gumball machine reporting was not _________. 5. Commonly used proxy for web services (two words). 7. Objectville matchmaking gimmick (three words). 11. A _______ proxy class is created at runtime. 13. Java’s dynamic proxy forwards all requests to this (two words). 16. In RMI, the object that takes the network requests on the service side. 17. The CD viewer used this kind of proxy.

2. Remote _________ was used to implement the gumball machine monitor (two words). 3. Similar to proxy, but with a different purpose. 4. Place to learn about the many proxy variants. 6. Proxy that protects method calls from unauthorized callers. 8. This utility acts as a lookup service for RMI. 9. Why Elroy couldn’t get dates. 10. Software developer agent was being this kind of proxy. 12. In RMI, the proxy is called this. 14. Proxy that stands in for expensive objects. 15. We took one of these to learn RMI.

Your design toolbox is almost full; you’re prepared for almost any design problem that comes your way.

import java.lang.reflect.*;

public class NonOwnerInvocationHandler implements InvocationHandler {
    PersonBean person;

    public NonOwnerInvocationHandler(PersonBean person) {
        this.person = person;
    }

    public Object invoke(Object proxy, Method method, Object[] args)
            throws IllegalAccessException {

        try {
            if (method.getName().startsWith("get")) {
                return method.invoke(person, args);
            } else if (method.getName().equals("setHotOrNotRating")) {
                return method.invoke(person, args);
            } else if (method.getName().startsWith("set")) {
                throw new IllegalAccessException();
            }
        } catch (InvocationTargetException e) {
            e.printStackTrace();
        }
        return null;
    }
}

PersonBean getNonOwnerProxy(PersonBean person) {

    return (PersonBean) Proxy.newProxyInstance(
            person.getClass().getClassLoader(),
            person.getClass().getInterfaces(),
            new NonOwnerInvocationHandler(person));
}

Design Patterns Crossword Solution

Who Does What? Solution

Match each pattern with its description: