Java Programming/Spring framework

This is intended to be a short, simple tutorial on writing a Java application that uses the Spring framework. Please note, this tutorial is intended for those with a moderate amount of background with Java, and a basic working knowledge of XML.

For this tutorial, we will be making an application that reads short stories from a Spring bean configuration file. (For the sake of this example, these short stories are real short stories.) There will be three Java classes, and one Spring config file. So let's begin…

Step 1: Setting up your environment
Before we can directly make the files, we first need to setup Spring. I'm assuming you already have the latest version of Java installed. If not, you can download Java Development Kit here.

Spring recommends to use Maven or Gradle to set up your dependencies. If you don't have them installed or provided by your IDE such as Eclipse, you can find instruction how to use and download them here and here. Maven or Gradle will make sure that your dependencies, and those they depend upon are loaded in your project.

See section QuickStart in http://projects.spring.io/spring-framework/ on how to add spring dependencies to your project. Using maven you will need to provide a pom.xml file with the following content in the root of your project:

If you are using Maven make sure that you provide a pom.xml file which contains the following line.

From here on out, you can just copy and paste the text into the files for Steps 2, 3, and 4; skip the explanations; and run the program yourself. The explanations are only there to provide you with a background of the way Spring puts it all together. Ok, now on to the meat and potatoes,.

Step 2: Creating a Spring beans configuration file
Create a new XML file in the directory where you are planning to put your java files. Call it. Then copy and paste the text below into the file and save it:

Explanation
The first two lines are just standard XML declarations. Technically we don't really need them, but we'll put them in anyway. Next, you'll see the  tag, this is where all the Java beans go.

Below that you'll see. This will be a bean for our Java class,  in package. This class is simply a placeholder for the List where we will be holding our stories. Note the attributes of the bean element: there must always be a class attribute to represent the Java Class the bean is using. The id attribute is optional; it is used by the XMLBeanFactory class, to tell it what bean to get with the getBean method: ex. . If no ID attribute is provided, like with, the class name is used as if it were the id attribute. Think:. Also note a bean's id value must not have any spaces, ex. don't write.

Next we have. The property tag just specifies what property variable in the Java bean file we want to specify with a bean property. The  tag is used next to tell Spring that we're dealing with a List of things, not just one. Next we have, this tells Spring to return the   bean inside this List. In a different example, you might simply need a list of values like Strings. For a grocery list you might have something like, Either way your property is mapped to a LIST

For our   story, we have. Hopefully, nothing too surprising here. There are three properties of this bean,,  ,. These are again mapping to property variables: title, author, content in the Story class. Within each value we have: Hello World! , User:Hyad, This is a simple story.

This is a story about a man who said, "Hello, World."

See, now wasn't that simple. Since we are dealing with Strings, everything between the start and end value tags is converted into a String. Hence to add a newline, we must actually put text on separate lines without any indentation. Be aware that values don't have to be mapped to Strings, they can be primitives like int or char, or objects like Integer or Float. Spring automatically knows how to convert them.

We won't be covering the OnceUpon bean, it's essentially the same thing as  , only with different values. In fact, that is the main purpose for using Spring, storing different sets of values for a Java class as a bean instead of making a new class. Up next are the Java Bean classes themselves.

Step 3: Making JavaBean classes
There are two JavaBean classes:  and , both in the package. Copy and paste the following text into their respective classes.

Explanation
Not too complicated, right? These are JavaBeans; simple classes with getters and setters for property variables, and a constructor without any parameters. For a more in-depth discussion of JavaBeans visit JavaBeans. The setters, like, are what Spring uses to create the beans in the XmlBeanFactory. The setters must follow specific bean naming conventions. For example,  with a lowercase "t" won't work. However, as an example  with property name "URL" will work because the second letter "R" is also capitalized in addition to the first "U". Getters aren't actually used by Spring in this example, however StoryReader needs them as we'll see later on. In addition, we don't actually have to specify a no-argument constructor, we could just leave it out and the Java compiler will automatically put one in the class when it's compiled. However, writing a constructor with one or more arguments without a no-argument constructor would invalidate the class as a bean.

Step 4: A main method to put it all together
As we have before, copy and paste the text. And save your class as.

Explanation
Here is our main class,  in package. First we have to import two Spring classes, XmlBeanFactory and ClassPathResource. XmlBeanFactory is essentially a Java class representation of the Spring XML configuation file,. However, before we can get the XML file, we have to tell Spring to look in our class path for that file. That's where ClassPathResource comes in. It searchs the class path, which is where our .class files are stored, for the file specified in its constructor, story_configuration.xml. Any other class that implements the Resource interface may be used, such as. Therefore, we see  creates a new bean factory from.

The next line,, tells us which bean we want to get next. The  tells the bean factory to return an object corresponding to the bean with the id " ", since it is the class name. Since it is an Object, we have to cast it into a  class.

Next, we get the list of stories from the  class, and loop through them. Since this is a bean, the Stories are already there in the list, within the values already in the stories. All we have to do is print them out; which we do. Note:  is used to escape quotes within the String.

Step 5: Running your program
So now that we're done creating our classes and files, lets run the program! Fix any errors you get by making sure you copied everything correctly. When you run the main method of, your output should be as follows:

Mar 12, 2006 5:42:30 PM org.springframework.core.CollectionFactory INFO: JDK 1.4+ collections available Mar 12, 2006 5:42:30 PM org.springframework.beans.factory.xml.XmlBeanDefinitionReader loadBeanDefinitions INFO: Loading XML bean definitions from class path resource [story_configuration.xml] "Hello World!" by User:Hyad: This is a simple story. This is a story about a man who said, "Hello, World." See, now wasn't that simple.

"Once Upon a Time" by Rob Yates: Once upon a time there were some interesting things going on. The end.

The dates will obviously be different when you run it yourself. Also, the four lines that begin with either a date or the word "INFO" are printed to System.err and may be above, or below, or even in between the rest of the output. This is because some operating systems may print to System.out and System.err at different times. Check that your output matches the one shown, disregarding the dates and order of the four lines that Spring prints. Now, you have a fully functioning Spring application, but what next?

Things to remember
As I mentioned earlier, Spring performs automatic conversion of values to both primitives and Objects;,  ,  ,  ,  ,  , you name it. Also note that, which is simply a list of values, can be mapped to a List object, an Array object, or a primitive array (the two square brackets kind). There are even  and   tags which can be mapped to  s and  s, respectively. And at any point you can replace a value with a reference to a bean, like replace myValue with. This reference will return the corresponding JavaBean and Spring will store it as that variable.

In addition, Spring can also serve as a replacement for properties files. An advantage is that Spring is XML based, so any XML parser can read it. And multiple beans can be stored for the same class within the same file. However, you may also place beans across multiple files, and use  to "import" other beans, just like importing Java classes.

The last thing you may want to know is that Spring is most helpful when you use one bean to reference to other beans, classes, files, etc. You may have one bean contain a list of beans, which contain a list of beans, each of which contain another list of beans, … This way only the file name and location of most top level bean is "hard-coded" in the Java class, and everything else is specified by the XML configuration files.

Try it yourself
Here are a few tasks you might do to make your Spring application more robust. Do as many, or as little, as you like:
 * Separate the StoryList bean into another XML file, using  in your new file.
 * Add publication date to each of your stories. How will you store the date?
 * Make a separate class for the author. What attributes might an author have?
 * Put additional functionality into StoryList. How about a printStories method that can be called by StoryReader's main method?
 * Create a writer so all output will be written to a file. And store that file name as a bean.
 * Add more stories. (Mine suck, I know.)
 * Instead of stories, how about TV shows, or video games?
 * Change random code around until it breaks. Have fun! :)

About the author
I go by User:Hyad on Wikipedia and Wikibooks. Having been frustrated by other Spring tutorials that were too long, I decided after actually learning (and using) Spring at work that I would actually create my own. This tutorial came the closest to what I was looking for in a good tutorial, but it was a little too short. So I figured, why not give an example that could be used in the real world. And I figured Wikibooks would be the best place for it, considering if I put it on my website, 1. It would be too cumbersome to edit, and 2. Other people wouldn't be able to edit and update it easily. So drop me a line at my Wikipedia talk page and tell me what you think.