Introduction

HowAbout is a Java application that queries online TV guides in order to display which events or shows will be broadcasted on a certain date.

I decided to write this application in order to keep track of my favorite sports events on TV without the need of checking an online TV guide.

License

This application is licensed under the New BSD License. I want to call your attention to the fact that the New BSD License has been verified as a GPL-compatible free software license by the Free Software Foundation, and has been vetted as an open source license by the Open Source Initiative.

Features

I wrote HowAbout while keeping in mind all of these features:

  • Pretty simple and concise code. No huge blocks of code, keeping it short and functional.
  • Highly extensive through an easy-to-implement plugin system. Add support to your favorite online TV guide with a simple interface implementation.
  • Written on an interpreted language, runs everywhere. No external calls, 100% pure Java.

You can help me improve that code if you want. Source code is fully available. Have fun with HowAbout!

Usage

HowAbout is very easy to use. When you run it in the first time, it will raise an error. Don't worry, that's because at the first run, there's no configuration file set, so HowAbout will create one for you. After running for the first time, a file named howabout.properties is now created with the following content:

#HowAbout Properties File
#Fri Mar 11 12:46:47 BRT 2011
class=
jar=

The class property refers to the full classpath to be called by HowAbout. It's the fully qualified name for the plugin main class that implements the HowAbout API.

The jar property refers to the plugin jar name. Don't forget to create a folder named plugins in the top directory of HowAbout and drop the plugin jar in there.

Check the following howabout.properties as an example:

#HowAbout Properties File
#Fri Mar 11 12:46:47 BRT 2011
class=net.sf.howabout.plugins.uolesporte.UOLEsportePlugin
jar=UOLEsportePlugin.jar

In this example, UOLEsportePlugin implements the HowAbout API and the value in the jar property refers to the plugin jar name dropped into the plugins folder.

If the plugin you are using or the one you wrote uses any external libraries, you need to drop those dependencies into the lib folder in the top directory of HowAbout.

If you try to run HowAbout with no parameters, you will see this:

HowAbout - An online TV guide searcher
Copyright (c) 2011, Paulo Roberto Massa Cereda
All rights reserved.

[ERROR][root] - The number of parameters is incorrect. HowAbout expects exact 4 parameters:

$ howabout WHAT on WHERE WHEN
            |        |     |
          genre  channel  day (today or tomorrow)

When searching for sentences, you must escape the parameters in double quotes, e.g.,

$ howabout news on "CNN in Spanish" today

You may also search using wildcards (#), e.g.,

$ howabout soccer on # today

I think it's self-explanatory. Type your query in there and let HowAbout fetch the events for you! Let's see an example of HowAbout presenting the results:

Running HowAbout

There we go, HowAbout makes it easy for you to find your favorite TV event or show! Hope you like it!

Plugins

So, you decided to write a HowAbout plugin, don't you? That's great! Let me tell how to do so! First of all, make sure to dowload the HowAbout API library, it's a small jar file with the interface definition and all classes you will need for HowAbout to recognize your plugin.

Your plugin must implement the HowAboutPlugin interface:

// package definition
package net.sf.howabout.plugin.api;

// needed imports
import java.util.List;
import net.sf.howabout.plugin.Event;
import net.sf.howabout.plugin.Query;

/**
* Provides a default standard plugin interface for writting HowAbout plugins.
* @author Paulo Roberto Massa Cereda
* @version 1.0
* @since 1.0
*/
public interface HowAboutPlugin {

    /**
* Returns all events found which match with the provided query.
* @param query A net.sf.howabout.plugin.Query object, which
* is set according to HowAbout parameters.
* @return A list of events. If no events are found, it returns an
* empty list.
*/
    public List<Event> getEvents(Query query);

    /**
* Get the plugin name.
* @return A string containing the plugin name.
*/
    public String getPluginName();

    /**
* Get the plugin version.
* @return A string containing the plugin version.
*/
    public String getPluginVersion();

    /**
* Get the plugin author.
* @return A string containing the plugin author.
*/
    public String getPluginAuthor();

    /**
* Get the plugin full package name.
* @return A string containing the plugin full package name.
*/
    public String getPluginFullPackageName();

    /**
* Get the plugin help.
* @return A string containing the plugin help.
*/
    public String getPluginHelp();

}

That's it, plain and simple! There is a plugin I wrote as reference called UOLEsportePlugin. It basically retrieves information from the online TV guide provided by UOL Esporte. The full source code is available with comments and hints. You may take a look on that in order to get a start point.

Although it's not mandatory, I'd like to recommend the use of the great jsoup, a Java library for working with real-world HTML. It provides a very convenient API for extracting and manipulating data, using the best of DOM, CSS, and jquery-like methods. This library can speed up the writting of HowAbout plugins.

Don't forget to build your plugin as a jar file, drop this jar into the plugins folder and configure the howabout.properties file. HowAbout takes care of the rest for you! By the way, let me know if you write a HowAbout plugin, so I can make it available in the code repository.

Download

HowAbout is licensed under the New BSD License. You may download the application, as well as the API and the plugins, in the compiled format or the source code as well. Please check the available releases in the project page hosted at SourceForge.net. You may also contribute with code if you want.

Running HowAbout

Contact

You can contact me through SourceForge.net. This website has an internal messaging system. If you prefer, you can also reach me through electronic mail:

Please, replace the first (#) symbol by (@) and the second and third (#) symbols by (.) cereda # users # sf # net

I also have a Twitter account, so you can follow me, if you want.

Project info

This application is platform independent, it will run wherever there's a Java Virtual Machine.

Project status

The current and stable release of HowAbout is 1.0. You can find the full source code in the project page at SourceForge.net or GitHub.

About me

Javadoc

Special thanks


Sorry if I forgot anyone or any project in particular.

Trivia

Unfortunately, something bad happened for me to develop this application. I was waiting the whole week for a certain soccer game in the Champions League, Arsenal versus Barcelona, and guess what, I just missed because I didn't pay attention to the schedule neither checked a TV guide. I got so angry, so I decided to write an app just to keep me informed of what events I can watch on TV, so HowAbout was born that day. It took me two days during my spare time to write it, and I just finished during the other game from the Champions League, this time Bayern Munich versus Internazionale Milano. I did miss that amazing game, but I just queried HowAbout to see when and in what time they'd gonna reprise that and voilà, watched the whole game!

Disclaimer

This website is hosted at SourceForge.net.

Java is a registered trademark of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.

Hosting


SourceForge.net

Project author

Paulo Roberto Massa Cereda, brazilian developer, programmer and somehow mathematician. Usually there's too much blood in my cafeine system.

Proud developer!