camiwilliams / captura

Langauge Education app

Captura

A language education application created for PennApps 2015. Captura showcases Clarifai's tagging endpoint (v1.0) using Java Maven and Apache Tomcat. When writing a Java Maven project, it helps to have Spring Tool Suite to organize your code and run Maven.

It will help if you read up on Tomcat and Java Maven to understand this project!

Note that the following explanation is not perfect, it is just the way I understand it! Feel free to propose changes to anything that could use better explanation :)

##Setting up your environment Once you have STS downloaded, open it and set up your environment for Tomcat. Once you see Tomcat under your 'Servers' tab, create a new Maven project and select 'archetype-quickstart' for your Archetype. Your GroupID is who owns the project (ie your name) and the ArtifactID is the name of your application.

Now you are ready to start using Maven! It is pretty icky, but I will try and explain everything to the best of my ability...

###This is what you NEED to do first

pom.xml This is the first file you need to know about, and it is the most important file ever. This is where your app will be verified and where all of your dependencies will be clarified (heh). Maven uses pom.xml dependencies instead of downloading jars. Yay. In order to see the raw code in STS, when you click on the file, go to the pom.xml tab. For now, you should just add the Clarifai dependency:

<dependency>
 	<groupId>com.clarifai</groupId>
 	<artifactId>clarifai-api-java</artifactId>
 	<version>1.1.0</version>
</dependency>

You can add more dependencies as you need them. To search for dependencies, go to [MVNRepository] (http://mvnrepository.com/)

/WebContent/WEB-INF/web.xml This file is important because it defines where to find your server logic and your HTML files. In Maven, HTML files are called JSP files. To define that you want the JSP to be viewed as HTML, you need to add servlet-mappings to your homepage. For this first mapping, your servlet-name should be your application name, and the url-pattern should be whatever file your initial page is under.

  <servlet-mapping>
    <servlet-name>captura</servlet-name>
    <url-pattern>/index.jsp</url-pattern>
    <url-pattern>/index.html</url-pattern>
    <url-pattern>*.html</url-pattern>
  </servlet-mapping>

In Maven, there are Servlets and Controllers. A servlet handles authentication logic like logging in, verifying and account, etc. A controller handles simple page logic, like using Clarifai or other APIs, or counting the number of llamas on a website. In web.xml, you will define your servlets. The servlet-name will be what you will refer to your servlet as in your JSP and the servlet-class is the filepath to your servlet. For the servlet-mapping, the name is the same as before, and the url-pattern should be /serv#, # being incremented with each servlet you add.

  <servlet>
    <servlet-name>LoginServlet</servlet-name>
    <servlet-class>camiwilliams.captura.servlet.LoginServlet</servlet-class>
  </servlet>
  <servlet-mapping>
    <servlet-name>LoginServlet</servlet-name>
    <url-pattern>/serv1</url-pattern>
  </servlet-mapping>

/WebContent/WEB-INF/yourprojectname-servlet.xml In this file, you define your controller and finalize the mapping between JSP and HTML. You can copy this file from me, because generally it is the same for everyone. The only thing you need to change here is context:component-scan to your controller package.

###Now you have the icky stuff done, let's do fun stuff! ####Web Stuff All of your JSP (aka HTML) files should be under 'WebContent/WEB-INF/jsp'. The only exception to this rule is your 'index.html' file, which should be located under 'WebContent/WEB-INF'. In my project, I have 'WebContent/frameworks', which contains any CSS I have, and 'WebContent/images', which contains all of my project images. For each page in your application, you need to create a new JSP file. This can get repetitive, but that is one of the many joys of Maven.

For the most part, these files are written exactly like HTML. The most important parts are the forms and the models.

Models look like ${message}. These insert code into the JSP from your controller before the page loads. We will look more at that later.

There are two types of forms I use in this project. One that calls my servlet, and one that calls my controller. The forms that call my servlet look as such:

<form action="LoginServlet" method="POST" style="display: inline-block;">
	...
	<input type="submit" class="form-control ptext" value="Login"/>
</form>

The action must be the name you specified under 'servlet-name' in your web.xml file. The method is up to you, you can do a POST or a GET. Finally, one input type must be 'sumbit' and have a value you will reference later.

The other form calls a controller and looks like this:

<form method="POST" action="settings.html" commandName="removeDictionary" style="display: inline-block">
	...
	<button type="submit" class="form-control ptext" style="display: inline-block">Remove Dictionary</button>
</form>	

In this case, I specify, again, my method either POST or GET, my action, which is the current page I am calling from, and the commandName, which is the function name. Again, we need one input or button type as 'submit'. In this form, we do not need to specify a value for the submit call.

And that's basically it for the web stuff!

####Server Stuff Now this is the most involved part. Server code is found in my 'src/main' folder. For the webapp side, just copy your index.jsp into the folder. For the java side, I divided it into 3 parts:

#####Launch The Launch code you can just copy directly. Be sure your webport is the same as specified under Tomcat, the default is 8080.

#####Servlet The Servlet code contains my LoginServlet, like I talked about before. Again, this code I mainly use for Authentication. You may or may not decide that you will need this. The important things to note for Serlvet code are as follows:

• Above the class declaration, you must include @WebServlet("/LoginServlet") which will be the same name as defined in your serlvet-name.
• Your servlet must extend HttpServlet
• Your form's method code must correspond to doGet or doPost

As far as implementing these functions, if you want to get a value from the form, you need to use request.getParameter("name"), where name is the value specified in the tag within the form. To redirect the page from the servlet, use rd = request.getRequestDispatcher("/new_user.html"); followed by rd.forward(request, response);.

#####Authenticator The Authenticator is where you read from your database. In this project, I used Firebase, but you can use Parse if that floats your boat, or even write your own database! From here, you will access your current user's information. If you are doing this for a hackathon, it doesn't have to be the most secure thing in the world. If you are looking to expand your project, I would recommend either encrypting this somehow, or scratching it and going for a different approach :) Regardless, any logic interacting with your database or the current user's state would be done in this file.

#####Controller Finally, the most fun part. Your controller! YAY! This part always takes the longest, because it is where the bulk of your code will go.

Before you start, make sure above your class declaration, you have @Controller. Above every method declaration, you need to include a @RequestMapping. This maps your JSP files to your functions. What does this mean? For every JSP file you have, you need to have a method mapping to it from your Controller. This is absolutely necessary and it is usually where the bulk of most silly errors comes from. Here is an example:

@RequestMapping(value = "/new_user", method = RequestMethod.GET)
	public ModelAndView handleNewUser(Model map) {
		String message = "<b>Welcome new friend!</b>";
		return new ModelAndView("new_user", "welcome", message);
	}

The value represents the page this method belongs to. A page can be accessed via a GET request or a POST request. Make sure that method of the form you attribute to navigating your page corresponds to the method of this function. Every function has the parameter Model map. This parameter is what allows you to insert code into the JSP file. In this case, we are adding the String message to the new_user.jsp file. In the JSP file, there would be a ${welcome} tag, where the message would go. You can also add these strings as a map, if you want to insert code in more than one place on a page.

Getting values from the JSP is slightly different from getting them for a Servlet. You would need to include a parameter in the method declaration. For my form that uploads a file, as a parameter I have @RequestParam("pic") MultipartFile file, where "pic" is the value as specified in the input of the form. Form file uploads are always received as MultipartFiles. These work with Clarifai, however require the following logic:

StringBuilder sb = new StringBuilder();
sb.append("data:image/png;base64,");
sb.append(StringUtils.newStringUtf8(Base64.encodeBase64(file.getBytes(), false)));

ClarifaiClient clarifai = new ClarifaiClient(APP_ID, APP_SECRET);
List<RecognitionResult> results = clarifai.recognize(new RecognitionRequest(file.getBytes()));

String first_tag = results.get(0).getTags().get(0).getName();

Besides that, the rest of this file is just like writting normal Java code. You can include functions that do not correspond to JSP pages as well. Not too bad!

#####Objects This is the least necessary part of your code, but also probably the most simple. It is where I defined object to make my code more readable. That's it!

###Let's run this thing! Now that we have all that junk done, let's run this thing! Right click on your project and click 'Maven build...' then under 'Goals' type 'clean install'. All should be running properly. Then, right click on your Tomcat server under 'Servers', and click 'Add and Remove'. Add your project, and run the Tomcat server. Assuming that ran properly, head over to your localhost:8080 and you should see your application! Yay!

This was a very general overview of what went into this project, if you have any questions, tweet me @cwillycs or email me [email protected] with the subject 'Hi Cami I h8 Maven'.

Best of luck!