Saturday, June 11, 2016

Basics: Just what IS an object, anyway?

This is a pretty long one by the standards of this blog.  Try to stay with it, though, the concepts are crucial.

Whether people are experienced developers used to procedural languages or newcomers to programming in general, really understanding objects tends to be a bit of a sticking point.  It's odd, because once you start to get it, everything seems quite natural.

An object is a representation of...  something.  Sometimes they represent fairly nebulous concepts, sometimes they represent very real physical things, but in all cases they're a kind of model.  Objects have properties, just like a flower has a color or a bee has [6] legs.  Objects have methods, which are really just things you can ask them to do, like 'release pollen' or 'sting someone'.  Finally, objects have events, or at least they can generate events.  That could be 'I've been pollinated' or 'I left my stinger in someone'.  Any particular object may make use of one, two or all three of these constructs.

Objects are based on classes in Java.  There is an all too human tendency to use the terms interchangeably and I've probably been guilty of doing that, too.  Technically, a class defines how an object should be built and an object is an instance of such a class.  Basically, after you write your code you compile it to create a .class file, and then when you run your code you can make a new object from said class. Making objects is easy enough, most of them get created (or instantiated) by using the new keyword like this:

    SimpleObject myObject = new SimpleObject();

Let's break that down:

First, we have declared that we're interested in working with a variable of type SimpleObject.  In other words, someone out there has written a SimpleObject.java file that defined a SimpleObject class and you're going to make an object from that definition.

That variable will be called 'myObject'.  We have to name our variables or we'd have a really hard time referring to them in our code!

We're not referring to a previously existing SimpleObject, we're going to make a completely new one.  The actual creation is handled by a constructor inside of SimpleObject.java, and we need to rely on that constructor doing its job, correctly setting up anything within the new object that needs to be in place.

Some objects don't appear to have constructors at all if you read the code, but that just means that there is no need for a constructor to do any setup work, so the programmer was able to rely on Java creating a default constructor for them.  The code for SimpleObject may have been written either way.  We don't care at this point, we just know we can call it.  I'll get back to constructors a little later when we talk about actually writing a class of your own.

Defining an class in Java is straightforward enough.  You don't really have to do any more than create a .java file with a bit of correct syntax.  The following example is enough to make a SimpleObject class (which really can't do anything but exist):

package com.oopuniversity.simpleobject;

public class SimpleObject {
}

Of course, a class that doesn't do anything isn't very useful, but I think it's good to have a picture in your head of all the 'extra' stuff that absolutely needs to be in place.  Code can look a bit busy to new developers, and its best to know what is basically template stuff that you should make sure is there and then ignore.

Just to break it down, that 'package' statement up at the top tells the compiler where the generated class file should go.  It's basically specifying an output directory, but using periods instead of slashes or backslashes.   Packaging is primarily an organizational tool and it turns out to be an important one later on.

Then we have 'public class SimpleObject' which tells us we're defining a class called SimpleObject.  That public keyword is important, it controls whether other objects in a larger program are able to create SimpleObjects or even refer to them at all.  For now, just use 'public'.  The day will come when you start to use other modifiers for specific reasons, but if you're reading this to learn you don't have those reasons yet.

Then we have some curly braces.  Those are ubiquitous in Java programs, and basically set boundaries for chunks of code.  In this case, they are setting the boundary for the beginning and end of the class, although they don't actually contain anything.  Anything between those brackets will be considered an attempt at having something be a part of SimpleObject.

Man, four paragraphs to describe three lines...  I guess a fair amount of information is consolidated down into even that useless bit of code!  Fortunately, that stuff always stays pretty much the same.  Once you understand that structure, you can kind of stop worrying about it and move on.

I mentioned above that I would talk about constructors.  Well, that time has come.  The following code is (aside from being in a different package) precisely identical to the previous code:

package com.oopuniversity.simpleobjectwithconstructor;

public class SimpleObject {
    public SimpleObject() {
    }
}

The only differences are:

  1. We changed the package definition, which lets us have this version of SimpleObject sit in the same project as the previous version without any conflicts.
  2. Now we have something new inside the braces that define the class.

The package definition is needed because I'm keeping everything inside one big project.  Just like you can't have two files with the same name in one directory, you can't have two classes with the same name in one package.

The new stuff inside the braces is defining a default constructor for SimpleObject.  It's public which means other objects can use it to make a new SimpleObject.  It has nothing between the parentheses, which means you can create a SimpleObject without having to give it any parameters, which are nothing more than pieces of information you give it (we'll talk about those soon).  Then it has some more of those fun curly braces, which again define boundaries.  Anything inside this particular pair of braces belongs not just to the class, but to the constructor itself.

Why would you want to write a constructor like this, making your class busier?  Well, you wouldn't, and that's why you get this for free with any class you write that doesn't bother defining a constructor of its own.  However, you DO need to know about and understand this for one simple reason:  It is also possible to define a class using a constructor (or a whole bunch of them if you like) that has parameters.  If you do this, the compiler will *not* create a default constructor for you and you won't be able to use a default constructor unless you explicitly write one.

https://github.com/OOPUniversity/OOP_Basics

Sunday, June 5, 2016

Put a Spring in your step

I don't know about you, but when it came time for me to figure out Spring's Java Annotation based configuration, I found it difficult to know what I really needed to do.  Between well-meaning but outdated online tutorials, many different versions of the software each with its own quirks, and some guys who just plain got it wrong, I found the process far more confusing than it should be.

In fact, once I stripped a program down to its most basic elements (and I don't think there's much left to do here at all), it's kind of embarrassing to think I ever had a problem with it.  In short, it's short.  I found myself left with three classes, a few annotations, and a working program.

Then just to gussy it up a bit, I created a complete alternate implementation of the entire package tree, which you can cause the program to use by specifying the package name as a command line parameter.  You can create other implementations as well, link them in via separate jar files and run those, too, so long as the classes in question implement the interfaces in the 'resources' package.

Without further ado, here is the Spring Java Config Demo.  I may update it with a few additional features in the days to come, but whatever I do add will be done in the most minimalist fashion possible.

JSON? What is this, Friday the 13th?

JSON stands for "JavaScript Object Notation", and it is nothing more than a standardized format for pushing object properties around in text format.  This is handy for many purposes, especially for transmitting objects over networks.  I can create objects in Java, convert them to JSON, and then read them in Javascript on a browser.  That's all kinds of handy.

There are plenty of tools for working with JSON,  I personally like Jackson from fasterxml.com.  This package provides a great deal of functionality in an easy to use form.  It's not the only JSON library out there, not by a long shot:  But it's simple, quick, and widely used.  It's also one of the core technologies selected for the 'DropWizard' framework, which I'll be talking about in another post.

Have an object and want to make a JSON representation?  Then ObjectMapper is the tool for you:

First of all, let's create a simple object called 'Person'.  For the sake of simplicity, we'll assume that all we care about is the name.

public class Person {
    private String givenName;
    private String surName;

    // This object has to be a Bean, which means it needs a no-argument constructor    

    public Person() {}

    public Person(String surName, String givenName) {
        this.surName = surName;
        this.givenName = givenName;
    }

    public String getGivenName() {
        return givenName;
    }

    public void setGivenName(String givenName) {
        this.givenName = givenName;
    }

    public String getSurName() {
        return surName;
    }

    public void setSurName(String surName) {
        this.surName = surName;
    }

    @Override    public String toString() {
        return "Person{" +
                "givenName='" + givenName + '\'' +
                ", surName='" + surName + '\'' +
                '}';
    }
}

This import statement is important, and of course you'll have to get the .jar file to support it.  I would suggest just using maven to deal with that.

import com.fasterxml.jackson.databind.ObjectMapper;

...
    ObjectMapper objectMapper = new ObjectMapper();
    Person p = new Person("Doe", "John");
    String jsonRepresentation = objectMapper.writeValueAsString(p);
    System.out.println(jsonRepresentation);

Going back the other way is even easier:

Person p2 = objectMapper.readValue(jsonRepresentation, Person.class);
This works very well within a single project of course.  Let's say you  need to persist your objects to disk for later use.  Well, the JSON representation gives you an excellent way to do this without running into the various issues that straight Java object serialization can raise.  Your files will be human-readable, human-editable, and they're much less likely to become unusable because you changed an object definition.  What's not to love about that?
In fact, reading and writing files is an extremely simple operation with Jackson.  The ObjectMapper does most of the hard lifting for you and turns basic (or not so basic) persistence into one line operations.  If you wanted to take that Person object up above and stash it in a file on your hard drive for later use all you'd need to do is this:
objectMapper.writeValue(new File("JohnDoe.txt"), p);
Reversing the operation is almost as easy:  You just need to use one special little piece of syntax to tell ObjectMapper what kind of object you are creating:

Person p2 = objectMapper.readValue(new File("JohnDoe.txt"), Person.class);
We've basically now recreated what we did in the first couple of examples, but we're able to run one example today and the next one tomorrow after restarting the computer if we want, since instead of just sitting in a String in our program's memory the important information is now sitting on your hard drive.  The file looks like this, by the way:
{"givenName":"John","surName":"Doe"}
JSON is also great for transmitting data over networks.  In fact, if you take a look at RESTful services (which I will visit in a future post) JSON is a standard way of communicating with them.  You don't even have to care what language the remote system uses.  Just so long as you both agree on the set of properties to be sent, the other end could be written in C, .NET, JavaScript (hey, look at what the 'J' stand for in the first place) or any other language.  Maybe the other end is also written in Java, but it was developed by someone else who doesn't have access to your library with your definition of Person.  That's perfectly OK, they can roll their own very easily and so long as the properties in your JSON are all supported everything will just work:
Let's pretend we are on the other side now, and the file created above was sent to us.  We want to bring the data into our system using our home grown "AnotherPerson" class.  For demonstration purposes, the class is exactly the same as the "Person" class above, except for the property names.  So it contains code like this:
public class AnotherPersonNoAnnotations {
    private String firstName;
    private String lastName;

    // This object has to be a Bean, which means it needs a no-argument constructor    

public AnotherPersonNoAnnotations() {}

    public AnotherPersonNoAnnotations(String lastName, String firstName) {
        this.lastName = lastName;
        this.firstName = firstName;
    }

    public String getFirstName() {
        return firstName;
    }

    public void setFirstName(String firstName) {
        this.firstName = firstName;
    }
    ...

When we try to read the object, we do this:
AnotherPerson p = objectMapper.readValue(new File("JohnDoe.txt"), AnotherPerson.class);
And it fails spectacularly!
Exception in thread "main" com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException: Unrecognized field "givenName" (class com.oopuniversity.json.model.AnotherPersonNoAnnotations), not marked as ignorable (2 known properties: "lastName", "firstName"])
 at [Source: {"givenName":"John","surName":"Doe"}; line: 1, column: 15] (through reference chain: com.oopuniversity.json.model.AnotherPersonNoAnnotations["givenName"])
at com.fasterxml.jackson.databind.exc.UnrecognizedPropertyException.from(UnrecognizedPropertyException.java:62)
...
The actual error will be followed by a whole bunch more stuff, but the important information is right at the top.  And notice:  This is an extremely useful error message.  It tells you exactly what went wrong and why.  It's an "UnrecognizedPropertyException" which means exactly what it says:  Jackson did not recognize a property it found.  Then it flat out tells you that 'givenName' is the problem.  It also tells you which properties it can recognize.  Then to top it off it shows you the exact JSON it was trying to read.  I wish all libraries were this good at telling us what went wrong.
So now we know that our object supports "lastName" and "firstName" but the data contains "givenName" and "surName".  Fixing this is quite simple.
Not to worry, even though we have different names for our properties we'll be fine.  This is far from an uncommon situation and Jackson has it handled.  All we need to do is add a couple of  'annotations' to our code.  Annotations are a clever addition that was made to Java years ago.  Classes, properties and methods can be annotated in order to add new behaviors.  In this case, we'll use them to inform Jackson that we are expecting different field names.  We change our 'AnotherPerson' class so that the declarations look like this:
public class AnotherPerson {
    @JsonProperty("givenName")
    private String firstName;
    @JsonProperty("surName")
    private String lastName;
I think that's pretty self-explanatory.  We're telling Jackson that when it's processing our file, it should think of our 'firstName' field as though it was called 'givenName', and of course the same thing applies to 'lastName' and 'surName'.  These annotations affect both reading and writing and now our class, while it uses our preferred variable names internally, looks to the outside world exactly like the Person class listed above.
Now our attempt to read the file works beautifully:
AnotherPerson{firstName='John', lastName='Doe'}
This is not all there is to say about  JSON processing with Jackson, but it is certainly a good start.  I'm sure I'll be talking about it more in posts to come.  I mentioned but did not talk about using this stuff to communicate between running systems (via RESTful services) and that's a key area that many developers will want to understand.
A code repository with working examples can be found here.
https://github.com/OOPUniversity/JSON_Basics

Friday, June 3, 2016

Super basic object stuff

I am not going to rework this right now, I think it gets the main points across as is.

From a recent Reddit post:

What you are asking about is quite basic to object oriented programming. Let's start with the first point I'd like to make: PersonA and PersonB are exactly the same thing, except the data is different. However, they cannot be simple methods that return integer values, that will never fly. The values you're setting up are lost as soon as the methods end.
Instead, you want to create objects of type Person. You do this by creating a class called Person and setting up variables to represent the values you want. At its absolute most basic (and this isn't correct, it's just showing the idea) it would look like this:
public class Person {
    public int x;
    public int y;
    public int range;
}
This is more akin to what we used to call a struct in c. Ordinarily you'd have a lot more stuff in there, but adding that right now could inhibit understanding so I want to take this slowly.
With the above class you could do this in the class you've posted:
public static void main(String [] args) {
    Person a = new Person();
    a.x = 200;
    a.y = 100;
    a.range = 160;

    Person b = new Person();       
    b.x = 100;
    b.y = 400;
    b.range = 170;
After that, you could use 'a.x' or 'b.range' the same way you were originally trying to use 'xA' or 'rangeB'.
Remember when I said that I was just showing the basics? Well, objects are a lot more powerful than just bags of variables. Let's use just another couple of features.
First, let's make a 'constructor' for Person so you can slim down your code:
public class Person {
    ... //What you already have
    public Person(int newX, int newY, int newRange) {
        x = newX;
        y = newY;
        range = newRange;
    }
}
Now your main can do this:
Person a = new Person(200, 100, 160);
Isn't that nicer?
Next, let's add 'accessor' methods to Person. Accessors are also called 'getters' and there are good reasons to use them. Trust me on this, I'm on the train and don't have time to fully explain:
public class Person {
    ... //What you already have

    public int getX() {
        return x;
    }

    //Do the same thing for 'y' and 'range'
}
At this point, you could still do 'a.x = 5' or 'range = b.range'. We can prevent that by marking the variables as 'private'
public class Person {
    private int x;
    private int y;
    private int range;
    ... //what you otherwise already have
}
But wait! Now when I try to write a.x=5 I get some horrible error and everything is broken and the world is ending!
No, you just need 'setters', also known as modifiers to do the job for you:
public class Person {
    ... //Everything you already have
    public void setX(int newX) {
        x = newX;
    }
    // Follow the same pattern for y and range
}
Now the equivalent to 'int range = a.range' is 'int range = a.getRange()', and the equivalent of 'a.range = 50' is 'a.setRange(50)'.
There's a LOT more to OOP, we've really just scratched the surface. But just encapsulating your data in this way will go a long way towards making your programs more readable, maintainable and robust.
I have no doubt that questions are coming up in your mind. I tried to make this clear and left out a few niceties in the interest of getting it written quickly and not overloading you, but it's a lot to absorb. Please ask questions when you need clarification.