Last week I did an introduction to Hyperscala and briefly outlined some really cool things it can do. This week I want to slow down a bit and take you through the basics of getting your first application up and running with Hyperscala.
Requirements: Since there is a broad number of IDEs / editors used for working in Scala I won’t make any presumptions in this tutorial regarding an IDE. However, I will quickly say that I use IntelliJ and absolutely love it for Scala development. That being said, the only requirements necessary to begin this tutorial is SBT and your editor of choice.
First we need to create our directory structure:
- hello-hyperscala/
- src/
- main/
- scala/
- hello/
- HelloPage.scala
HelloSite.scala
build.sbt
Now lets create our build.sbt file in the hello-hyperscala folder with the following contents:
This is a fairly simplistic build.sbt file with just a few specifics to note. First, we need the Typesafe Repository because one of Hyperscala’s dependencies uses Akka Actors. The external repo will not be required once we upgrade to 2.10 but because of some known bugs in 2.10 that undertaking is currently on hold. The second thing to notice is the hyperscala-web dependency. The web sub-project of Hyperscala provides the functionality to create a Website and Webpages. There are several sub-projects in Hyperscala (core, html, javascript, svg, web, ui, examples, and site) but web is the highest level we need and depends on the rest of the functionality we want to use right now.
Next we need to create our actual webpage:
You’ll name this HelloPage.scala and put in the hello directory as reflected in the structure above. It’s fairly simple what we’re doing here. We’re extending from Webpage that defines the basic HTML structure (html, head, body) and we can then add content on to it. We set the page title and add “Hello World!” to the body of the page.
Next we need to create a Website. The website is responsible for routing URLs to pages, managing access to the session, and much more. So here’s our very basic website:
You’ll name this HelloSite.scala and put it in the hello directory with HelloPage.scala. We simply define the val page that represents the URI /hello.html to point to a new HelloPage. The second argument is a function, so every request creates a new instance of HelloPage. We talked about Scope in the previous article but for the purposes of our do-nothing page we just have it create the page, render it, and then die when a request comes in. By default a WebpageResource will automatically add itself to the Website so there’s no need to explicitly add it. Lastly, the createSession is responsible for creating a new Session that is used throughout the website across all pages.
Now that we’ve got all of our code written we simply need to run it. Issue the following command:
You should end up with some output like the following:
Notice the “bound to *:8080” signifies that it is wildcard bound to all IP addresses and on the port of 8080. Now just open up your browser and hit http://localhost:8080/hello.html and you should be greeted with “Hello World!”.
Nice framework!
I have just tried the getting started. A few things that I run into:
1)
I got the SBT warning:
org.hyperscala#hyperscala-web_2.9.0;0.6: not found
I solved this by changing the Scala version to 2.9.2 in build.sbt.
2)
Going to http://localhost:8080/ resulted in a http 404 error, but going to http://localhost:8080/hello.html did work.
3)
The resulting HTML that is generated by Hyperscala is as expected except that the "html" tag is replaced by "null". Is this a bug?
Another question, is Hyperscala running on Servlets/ServletFilters?
1.) Yes, Hyperscala has not been upgraded to 2.10 yet because of some existing bugs in the 2.10 release. They will be fixed in 2.10.2 so I will likely wait until then to do the upgrade.
2.) Thanks, that was a mistake on my part. I updated the post to reference the correct URL.
3.) There was a bug in that version of Hyperscala and I've updated the post to reference 0.7 instead of 0.6 and it should work correctly now.
When I first started writing Hyperscala I was using Servlets but ran into a lot of performance problems and compliance issues with WebSockets. I finally decided to build a layer on top of Netty to allow a much higher level of performance and greater flexibility of implementation. However, there are plans to build out an abstraction layer that will allow running in a Servlet Container or under Netty I just haven't had anyone using Hyperscala request it yet.
To be honest I'm surprised how few people really need to run in a Servlet Container. It is also amazing to me how much greater the performance is when running in Netty.
Being able to run Hyperscala webapps on a Servlet Container would be useful for those who have Java EE applications.
It can also be needed when a website is composed out of multiple webapps, each under a different requestURI, for example:
/static, for static resources (according to some benchmarks, Tomcat is fast in serving static resources. Faster than HTTPD. Not sure if it is also faster than Netty.)
/admin, which maybe runs a admin control panel using the JavaScript outputting non-searchengine-indexable GWT webframework for a desktop feel.
/, running Hyperscala webframework.
/manager, running the standaad Tomcat manager to manage all the apps
/insight, running Spring Insight to diagnose all webapps running on the server.
Sometimes third-party Servlet Filters are needed for webapps. For example UrlRewriteFilter, to perform urlrewriting.
Another reason might be when webapps need to be hosted at Cloud platforms that might only support Servlet based webapps.
@jtict, I agree that Servlet support is something that is important and is on the agenda in the near future. I used to use Servlets exclusively and Tomcat primarily as the container. The two things that made it necessary for me to move away from Tomcat was 1.) the lack of support for wildcard virtual host mappings (ie. *.hyperscala.org mapped to a webapp) and 2.) the lack of good WebSocket support.
There is actually a solution I've been working on that offers a similar solution to a Servlet Container currently just named Website Manager. The major distinction is that it proxies communication to processes instead of running all the webapps in one JVM. This does require a bit more memory but offers a lot of really powerful features for hot-deploying and higher-level interaction. I'll be releasing that in the near future.
i have write your code into my project but there have some errors.
class myWeb extends Webpage {
title := "Hello world page"
body.contents += "hello world!"
}
error:: cannot resolve symbol := 、 += 、 contents
i am a newer to scala , so i just want to know why? can you give me an answer? Thanks
@brighter, import org.hyperscala.html._ to get an implicit conversion for String to tag.Text.