decoration decoration
Stories

GROKLAW
When you want to know more...
decoration
For layout only
Home
Archives
Site Map
Search
About Groklaw
Awards
Legal Research
Timelines
ApplevSamsung
ApplevSamsung p.2
ArchiveExplorer
Autozone
Bilski
Cases
Cast: Lawyers
Comes v. MS
Contracts/Documents
Courts
DRM
Gordon v MS
GPL
Grokdoc
HTML How To
IPI v RH
IV v. Google
Legal Docs
Lodsys
MS Litigations
MSvB&N
News Picks
Novell v. MS
Novell-MS Deal
ODF/OOXML
OOXML Appeals
OraclevGoogle
Patents
ProjectMonterey
Psystar
Quote Database
Red Hat v SCO
Salus Book
SCEA v Hotz
SCO Appeals
SCO Bankruptcy
SCO Financials
SCO Overview
SCO v IBM
SCO v Novell
SCO:Soup2Nuts
SCOsource
Sean Daly
Software Patents
Switch to Linux
Transcripts
Unix Books

Gear

Groklaw Gear

Click here to send an email to the editor of this weblog.


You won't find me on Facebook


Donate

Donate Paypal


No Legal Advice

The information on Groklaw is not intended to constitute legal advice. While Mark is a lawyer and he has asked other lawyers and law students to contribute articles, all of these articles are offered to help educate, not to provide specific legal advice. They are not your lawyers.

Here's Groklaw's comments policy.


What's New

STORIES
No new stories

COMMENTS last 48 hrs
No new comments


Sponsors

Hosting:
hosted by ibiblio

On servers donated to ibiblio by AMD.

Webmaster
A Simple API Analogy | 237 comments | Create New Account
Comments belong to whoever posts them. Please notify us of inappropriate comments.
A Simple API Analogy
Authored by: TJ on Saturday, April 21 2012 @ 06:16 AM EDT
By their very purpose analogies are never perfect.

The car analogy works in a general sense since almost everyone understand how
cars are driven and that they all implement the same interfaces for controlling
the vehicle.

I was trying to get away from anything technical.

[ Reply to This | Parent | # ]

A Simple API Analogy
Authored by: TJ on Saturday, April 21 2012 @ 07:02 AM EDT

What I forgot to explicitly write in my original exposition of the API was that the Vehicle API can be further understood if we think of inputs and outputs.

The Vehicle API states that there is a steering-wheel Object and that it accepts Input in the form of movement clockwise or anti-clockwise.

In response to that input its Output is to cause the road wheels to change their alignment relative to the vehicle and, if the vehicle is moving forwards, cause the vehicle to turn in the direction of the input.

That might be described, in an object oriented language such as Java as:

package net.groklaw.vehicle;

class SteeringWheel {

public:
/**
* The steering wheel controls the direction of travel of
* the vehicle indirectly by translating the driver input
* into changes in the position of the road wheels.
*
* @param rotation degrees of rotation (+ or -) to add to the current SteeringWheel position
* @return the new absolute position of the SteeringWheel (where 0 is centred, negative is left turn, positive is right turn)
*/
float rotate(float rotation);
/**
* Get the current position of the steering wheel
*
* @return the current +/- rotation in degrees
*/
float getPosition(void);
/**
* Force the steering wheel to return to the neutral position
*/
void returnToCenter(void);
};

And we might use it thus:

import net.groklaw.vehicle.SteeringWheel;

bool ourMethodToControlSteering(void) {
bool result = true; // assume it works
float direction;
SteeringWheel sw = new SteeringWheel();

sw.returnToCenter();
direction = sw.getPosition();
System.out.println("Steering position %f", direction);

// check the steering will rotate both ways
sw.rotate(-180);
direction = sw.getPosition();
if (direction != -180) {
System.out.println("Steered -180, got %f", direction);
result = false;
}

sw.returnToCenter();
sw.rotate(180);
direction = sw.getPosition();
if (direction != 180) {
System.out.println("Steered 180, got %f", direction);
result = false;
}

return result;
}

Other developers could write their own implementation of class SteeringWheel and its methods based on the API above. Our application could make use of their implementations provided they use the same class name and method signatures (return type, method name, argument types).

The API does not reveal the copyrighted source-code implementation of my class SteeringWheel. Other implementations do not need to reveal their source-code provided they write it to match the API.

[ Reply to This | Parent | # ]

Groklaw © Copyright 2003-2013 Pamela Jones.
All trademarks and copyrights on this page are owned by their respective owners.
Comments are owned by the individual posters.

PJ's articles are licensed under a Creative Commons License. ( Details )