====== The Rules class ======

The core of every PBEM game run by the Engine is the Rules class. It defines the basic functionality for each game, and tells the Engine where to look for specific bits of functionality. Most parts of the Engine work using a declarative programming model. But more about that later, first let's look at the class:

<code java>
/*
 * YOUR PROGRAM NAME
 * YOUR COPYRIGHT NOTICE
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.

 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
package nl.pbemengine.tutorial;

import nl.pbemengine.engine.ng.base.entity.Mail;
import nl.pbemengine.engine.ng.blueprint.MailProcessor;
import nl.pbemengine.engine.ng.blueprint.Ruleset;
import org.hibernate.Session;

/**
 * A fresh ruleset
 * @author YOUR NAME
 */
public class Rules extends Ruleset {
    public final static String CURRENT_VERSION = "1.0.0";

    /**
     * Create a new instance of this Ruleset
     */
    public Rules() {
        super("Ruleset Name", // TODO: Change
            "Ruleset Web Context", // TODO: Change
            MyTurnProcessor.class, // TODO: Change name
            MyReportGenerator.class // TODO: Change name
        );

        // TODO: Call addPersistentClass for Hibernate entities
        // TODO: call addWireableClass for classes you want to be able to inject
        // into other objects
        // TODO: Call addWebAction for any webpages you want to use for this ruleset
    }

    /**
     * A MailProcessor class appropriate for a given mail
     * @param m The mail to check for an appropriate processor
     * @return A class that is an extension of MailProcessor
     */
    @Override
    public Class<? extends MailProcessor> getMailProcessor(Mail m) {
        // TODO: Add logic for different types of mails here
        return MyMailProcessor.class;
    }

    /**
     * Called when a Ruleset is loaded for the first time, will initialize the ruleset
     * @param session The Hibernate session used for initialization
     */
    @Override
    public void install(Session session) {
        // TODO: create install commands
    }

    @Override
    public boolean isUpToDate(String version) {
        // TODO logic for determining if installed version is most recent
        // version
        return version.equals(CURRENT_VERSION);
    }

    @Override
    public void upgrade(Session session, String version) {
        // TODO logic for performing an upgrade from a previous version
        // to the current version
    }
}
</code>

As you can see by the elaborate list of TODO comments, there are quite a few things we need to do to make a working PBEM. Fortunately, most of these tasks are easy, but they do require a bit of explanation. For now - we just make a slight change to the constructor of the Rules class:

<code java>
public Rules() {
        super("Rock Paper Scissors",
            "rps",
            MyTurnProcessor.class, // TODO: Change name
            MyReportGenerator.class // TODO: Change name
        );

        // TODO: Call addPersistentClass for Hibernate entities
        // TODO: call addWireableClass for classes you want to be able to inject
        // into other objects
        // TODO: Call addWebAction for any webpages you want to use for this ruleset
    }
}
</code>

All we did was change the superclass call. The first parameter simply indicates the name of the game (in this case: Rock Paper Scissors), the second parameter tells the Engine's builtin webserver to reserve the path "/rps" for our game - we will get back to this later when we start creating our web interface.

Also, let's not forget to edit the copyright notice:

<code java>
/*
 * Rock Paper Scissors PBEM Tutorial
 * (C) 2009 Jeroen Steenbeeke
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.

 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 */
</code>

Again (and we can't stress this enough) - [[:licensing|you are creating a derivative work of the PBEM Engine]] and are therefore bound to the GPL. Since you are writing your own code, you should put your own name and copyright notice on top but you can't remove the GPL header, and are in fact required to add it to every source file you make. You can setup your IDE to do this for every new file you generate (usually under an option called Templates).

Next: [[how_to_make_your_own_pbem:entities|Creating entities]]