Instructional Material: Interfaces

Just as a class is a description of an object, an Interface is a description of a class. An Interface defines the fields (variables) and methods that a class must provide (public access) to users of the class. The Interface does not define how a class derives the value of a field or the result of a method, only that a class that implements an Interface must expose that Interface's fields and methods. As such, the Interface defines a public facing API that the class must provide. Interfaces are also called Contracts, in that the Interface defines a contract or agreement (in terms of the fields and methods exposed) between a class and users of that class. Classes may extend only one (parent) class but classes may implement any number of interfaces.

One power of Interfaces is that any class that implements an Interface can be used where ever that Interface is defined as a required data type. This concept is best explained by an example.

A simplifed view of the PIDController class in the FRC library shows a constructor that takes two classes as input, a PIDSource object and a PIDOutput object. PIDSource and PIDOutput are both Interfaces. Digressing for a moment, a simplified PIDController needs two things to perform its function. An input or process control value that will be used by the PIDController to compute an output value, which must be sent to some other class for action. Now in many cases the input value will come from an encoder (counts) and the output value will go to a motor (power). You could define the PIDController class constructor as Public PIDController(Encoder enc, Motor motor). There are two problems with this. First, the PIDController class and the Encoder and Motor classes have not agreed on how data will pass between the Encoder and PIDController class and how data will pass between the PIDController and Motor class. The second issue is that the PIDController as defined will only work with Encoders and Motors. What if we wanted to use some other classes as the input and output objects? Interfaces solve both of these problems.

The simplified PIDController class constructor actually looks like this: Public PIDController(PIDSource source, PIDOutput output). PIDSource and PIDOutput are Interfaces and they define what fields and methods are required for any class that wants to act as a PID source or PID output object. These Interfaces define the contract between the PIDController class and any class wanting to act as a PID source data provider or a PID output data consumer. The example Interfaces look like this:

A class implementing the PIDSource Interface must provide a method defined as double pidGet(). That method must return the current input value to be used by the PIDController. Since any class passed into the PIDController constructor for input must implement the PIDSource Interface, the PIDController now knows what method to call on the source object reference variable to get the input value. For instance, the Encoder class implements PIDSource and as such must provide the method pidGet() along with its other methods. When pidGet() is called, the Encoder returns the current tick count. So an Encoder object can be passed to the PIDController constructor. But so can any other class that implements PIDSource. A class implementing the PIDSource Interface would look like this:

Any class that implements PIDOuput must provide the pidWrite(double value) method. That method when called, will take the passed value and perform some action with it. The PIDController knows that any class implementing PIDOutput will have  the pidWrite() method and so it knows how to send the output value it has calculated from the input, by calling the pidWrite method on the output object reference variable. A class implementing the PIDOutput Interface would look like this:

For instance, the Motor class implements PIDOutput and provides the pidWrite(double value) method and sets it's motor power from the value. So a Motor object can be passed to the PIDController constructor as an output object. But so can any other class that implements PIDOutput.

A simplified PIDController class would look like this:

An example of using these classes:

The key here is that the single implementation of the PIDController class can handle both the custom source and output classes as well as the standard encoder and motor classes.

Classes can implement more than one Interface along with any other fields or methods they wish. Interfaces are very powerful and allow a class expecting an Interface (like PIDController) to work with any number of other classes that implement that Interface.

Note that Interfaces only define the expected fields and methods to be exposed by the implementing class. The actual implementation (code) is contained in the class implementing the Interface.

Like many things in Java (and other languages), this is a basic introduction to Interfaces. There is a lot more to Interfaces which you can read about here. Here is a video on interfaces. This lesson should be enough to understand Interfaces and use them in your robot code.