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

Old McDonald had a File, IO IO IO

One of the most basic and common functions we programmers have to implement involves reading and writing data files. So get used to doing so. The good news is that Java is well equipped with many library functions for doing this. The bad news is exactly the same. There are many library functions, so many that you can get lost in them. In fact, just when we thought we had a handle on the 'java.io' package, along came 'java.nio' (New I/O) to cloud the picture even more. Even an experienced programmer can get a little lost in the multiple classes that are in place for dealing with persistent data, and I certainly don't want to overwhelm my audience, so I'm going to stick to some basics.

 First off, I'm going to pretend that 'new I/O' never happened. I'm also going to offer you only a subset of all the functionality that's out there even in the java.io library. When it comes down to it, when you've got a file to read or write, you want to be able to just do so, without a lot of muss or fuss.

I am going to have to assume that you're reasonably familiar with directories (or folders, if you must) and files as seen by your operating system. I'm going to assume that you understand what a text file is, and that you feel reasonably comfortable with viewing them or editing them with notepad, or UltraEdit, or whatever your choice of text editor might happen to be.

First, a note on file types. There are of course a huge number of file formats out there, to support applications from AutoCAD to PhotoShop to Visual Studio, but all files can be pretty much divided into to major categories: Text and Other. Text files are broken down into lines, and many programs deal with them on a line by line basis. Other files tend to consist of plain old blocks of information, whether those be pixels for an image, or a song or movie, or quite literally anything else you can save.

Java supports both major file types of course, and has objects specifically for dealing with each. When dealing with text files it's very convenient to read or write things one line at a time, so we have that ability in our libraries.

We've used an object we call 'PersonData' before, and we'll make use of it again now.  Suppose we had a file in which we had a bunch of last names and first names stored, for now we'll assume that last names and first names each appear on a line, so the file would look something like this:

PEOPLE.TXT

    Schmoe
    Joe
    Doe
    John
    Smith
    Bill

So we've got the information here to support three PersonData objects, all contained within a file called PEOPLE.TXT.

If we wanted to read the names from this file and create PersonData objects, it's conceptually pretty simple:

Open the file for reading
As long as there's something to read
    Read a last name
    Read a first name
    Create a PersonData object with those values

That makes sense, right?

Enter the Scanner.  The Scanner object is pretty new, and frankly I'm still not completely used to it.  But it's so darned handy I have no excuse not to use it.  The Scanner has several different constructors, but we're going to make use of the one that uses the File object right now.

First, let's define the file that we intend to read.  This sets us up for the next step:

File personFile = new File("PEOPLE.TXT");

Note that this isn't something that will fail, even if PEOPLE.TXT does not actually exist.  Maybe we intend to create it next, or we want to test for its existence.  The File object is handy that way.

Scanner personScanner = new Scanner(personFile);

This can fail.  If personFile refers to a non-existent file bad things can and will happen starting here.  Proper code will be wrapped up in try/catch blocks as I discussed when we talked about exception handling.

At this point we have covered the first line of our pseudo-code algorithm:  "Open the file for reading".  The next part was "As long as there's something to read", which a Scanner can handle quite easily:

while (personScanner.hasNextLine()) {

This loop will now run until we're out of lines.  That's pretty convenient.  Now let's extract the last and first names:

    String lastName = personScanner.nextLine();
    String firstName = personScanner.nextLine();

Yes, there's a weakness or three here.  We're making the assumption that our file is correctly formatted and complete, with two lines for every person.  Good coding practice would include checking 'hasNextLine' in between those two lines and dealing with it if that isn't the case.

We're actually almost done here.  Once we've got the last name and the first name, we can go ahead and create a PersonData object:

    PersonData personFromFile = new PersonData( firstName, lastName );

At this point, technically we can end the loop.  We've done the specified job, although realistically this is useless.  There's not much point in reading a data file only to toss away the data.  You'd want to do something with these 'personFromFile' objects, like adding them to a List or Map, or storing them in some other sort of data structure your program will use.

But for now, we'll just pretend we're doing that and close down the file:

}
Scanner.close();

And that's about all there is to reading text files since Java 7 came out.  It was a bit more difficult before, when we had to create a couple of other objects in place of Scanner, and if the data included numbers or multiple items on one line it was even more involved.

Let's say that the file was formatted like this instead:

PEOPLE.TXT

    Schmoe Joe
    Doe John
    Smith Bill

That seems reasonable, right?  It is, and it's pretty easy to deal with.  All we'd need to do is change the following two lines from this:

    String lastName = personScanner.nextLine();
    String firstName = personScanner.nextLine();

To this:

    String lastName = personScanner.next();
    String firstName = personScanner.nextLine();

And we will have accomplished our goal.  We could also have done this:

    String lastName = personScanner.next();
    String firstName = personScanner.next();

    String anythingLeftover = personScanner.nextLine();

What is important is to realize that 'nextLine' is critical to advance us from one line to the next, so we have to use it before we go through the loop again.

Before I go, I also want to mention that Scanner is capable of reading not just Strings, but also any of the primitive data types as well.  It supports nextInt(), nextDouble(), etc.  It's also capable of reading more complicated input via the use of Regular Expressions, which are a huge topic in their own right.  Regular Expressions essentially provide an entire language for matching complicated text, and an entire series of articles could no doubt be written just on that topic alone.

In our next episode, we'll talk about writing text files, which is just the reverse of what we've done here.