Part II: Setting up Mercurial Repository (Command Line)

From Notes

Jump to: navigation, search

Contents

Introduction

The jar file you downloaded in the previous tutorial is a Mercurial repository. In this tutorial we will make additional changes to the HcryptoJ code base and share our changes with each other.

If you haven't already down so, you should complete the following tutorials:

Initializing the Mercurial Repository

Because the jar file you downloaded was already set up as a Mercurial repository, there are no initialization steps to perform. To see the latest revision (usually referred to as the tip) of the repository's default branch you can use the parents command and you should see the following:

$ hg parents
changeset:   14:2f8f39e5be3a
tag:         tip
user:        Ralph Morelli <ram8647@gmail.com>
date:        Wed May 18 06:37:04 2011 -0400
summary:     Updated the README file.

This provides the who, what, and where of the latest revision. To see the complete history of the repository -- i.e., all revisions -- use the 'log command.

$ hg log
changeset:   14:2f8f39e5be3a
tag:         tip
user:        Ralph Morelli <ram8647@gmail.com>
date:        Wed May 18 06:37:04 2011 -0400
summary:     Updated the README file.

changeset:   13:43ad6c6390b5
user:        Ralph Morelli <ram8647@gmail.com>
date:        Wed May 18 06:33:15 2011 -0400
summary:     Added Eclipse .project file

changeset:   12:fc2a333f69e6
user:        Ralph Morelli <ram8647@gmail.com>
date:        Wed May 18 06:30:25 2011 -0400
summary:     Modified Caesar cipher.

(...)

Committing the Current Change Set

Let's commit the changes that were made during the previous tutorial, where you created a Null cipher as a plugin. If you check the current status of the repository you should see something like this:

$ hg status
M META-INF/MANIFEST.MF
M classes/plugins/PluginProvider.class
M src/plugins/PluginProvider.java
? classes/plugins/NullEngine.class
? classes/plugins/NullKey.class
? hcryptoj-hg-repo.jar
? src/plugins/NullEngine.java
? src/plugins/NullEngine.java~
? src/plugins/NullKey.java
? src/plugins/NullKey.java~
? src/plugins/PluginProvider.java~

The files marked with 'M' are files that you modified in performing the previous tutorial. The files marked with ? are files that are not currently being tracked by Mercurial.

The first thing we want to do, is add the new files that we want to track to the repository -- i.e., tell mercurial to track changes to those files. The -I option allows us to use wild cards to describe path names.

$ hg add -I src/plugins/*.java
src/plugins/CaesarKey.java already tracked!
src/plugins/PluginProvider.java already tracked!

$ hg add -I classes/plugins/*.class
classes/plugins/CaesarKey.class already tracked!
classes/plugins/PluginProvider.class already tracked!

109add49afd3:hcrypto-download rmorelli$ hg status
M META-INF/MANIFEST.MF
M classes/plugins/PluginProvider.class
M src/plugins/PluginProvider.java
A classes/plugins/NullEngine.class
A classes/plugins/NullKey.class
A src/plugins/NullEngine.java
A src/plugins/NullKey.java

(...)

Next let's commit the changes.

$ hg commit -m "Added Null cipher plugin."
$ hg parents
changeset:   15:9ffea19504e9
tag:         tip
user:        Ralph Morelli <ram8647@gmail.com>
date:        Wed May 18 07:23:00 2011 -0400
summary:     Added Null cipher plugin.

Creating A New Cipher Plugin

For this exercise, each team will create its own new cipher plugin and then share it with the rest of the group.

To keep with the Mercurial practice of isolating self-contained tasks from other development tasks, let's create a new clone of our local repository, named hcryptoj-hg-new-cipher, and use it to perform this new development task.

You'll want to run the hg clone command from the parent directory of your local repository:

$ cd ..
$ hg clone hcryptoj-hg-repo/ hcryptoj-hg-new-cipher
updating to branch default
218 files updated, 0 files merged, 0 files removed, 0 files unresolved

$ cd hcryptoj-hg-new-cipher/
$ hg parents
changeset:   15:9ffea19504e9
tag:         tip
user:        Ralph Morelli <ram8647@gmail.com>
date:        Wed May 18 07:23:00 2011 -0400
summary:     Added Null cipher plugin.

Make up a name for your cipher and then copy and rename the NullEngine.java and NullKey.java files with your cipher name. My cipher will be called "MySilly":

$ cp src/plugins/NullEngine.java src/plugins/MySillyEngine.java
$ cp src/plugins/NullKey.java src/plugins/MySillyKey.java
$ hg status
? src/plugins/MySillyEngine.java
? src/plugins/MySillyKey.java

You will have to add the name of your cipher to the PluginProvider constructor:

    public PluginProvider(String name) {
        this.name = name;
        put("Caesar", "plugins.CaesarEngine","plugins.CaesarKey");
        put("Null", "plugins.NullEngine","plugins.NullKey");
        put("MySilly", "plugins.MySillyEngine","plugins.MySillyKey");
    }

To complete the cipher definition you have to modify the the MySillyEngine.java and MySillyKey.java. In addition to the standard changes -- changing the class name, etc. -- you will have to rewrite the engineEncode() and engineDecode() methods.

Here are some example encode and decode methods, all of which work only for lower case (az) alphabets:

// Plain: abcdefghijklmnopqrstuvwxyz
// Crypt: badcfehgjilknmporqtsvuxwzy
public String engineEncode(String s ) throws Exception {
   char ch = s.charAt(0);
   int indx = ch - 'a';
   if (indx % 2 == 0)
      indx++;
   else
      indx--;
   return "" + (char)('a' + indx);
}
// Crypt: badcfehgjilknmporqtsvuxwzy
// Plain: abcdefghijklmnopqrstuvwxyz
public String engineDecode( String s ) throws Exception {
   char ch = s.charAt(0);
   int indx = ch - 'a';
   if (indx % 2 == 1)
      indx--;
   else
      indx++;
   return "" + (char)('a' + indx);
}
// Plain: abcdefghijklmnopqrstuvwxyz
// Crypt: zyxwvutsrqponmlkjihgfedcba
public String engineEncode( String s ) throws Exception {
    char ch = s.charAt(0);
    int indx = ch - 'a';
    return "" + (char)('a' + (25-indx));
}
// Crypt: zyxwvutsrqponmlkjihgfedcba
// Plain: abcdefghijklmnopqrstuvwxyz
public String engineDecode( String s ) throws Exception {
    char ch = s.charAt(0);
    int indx = ch - 'a';
    return "" + (char)('a' + (25-indx));
}

Updating the Original Repo

After making these editing changes, you will have to rebuild (ant build) your project and test whether your cipher works correctly. It should be able to correctly encrypt and decrypt strings of lowercase letters. A good test message would be abcdefghijklmnopqrstuvwxyz.

Once you have determined that your implementation is correct, you will want to commit your changes. Before you do that, you should add the new files you created to the repository so Mercurial will track them:

$ hg add src/plugins/MySillyKey.java
$ hg add src/plugins/MySillyEngine.java 
$ hg add classes/plugins/MySillyKey.class
$ hg add classes/plugins/MySillyEngine.class
$ hg status
M classes/plugins/PluginProvider.class
M src/plugins/PluginProvider.java
A classes/plugins/MySillyEngine.class
A classes/plugins/MySillyKey.class
A src/plugins/MySillyEngine.java
A src/plugins/MySillyKey.java

The commit command is as follows:

$ hg commit -m "Added the MySilly plugin cipher."
$ hg status
$ hg tip
changeset:   16:85e65bf74d06
tag:         tip
user:        Ralph Morelli <ram8647@gmail.com>
date:        Wed May 18 07:37:39 2011 -0400
summary:     Added the MySilly plugin cipher.



$ hg log
changeset:   16:85e65bf74d06
tag:         tip
user:        Ralph Morelli <ram8647@gmail.com>
date:        Wed May 18 07:37:39 2011 -0400
summary:     Added the MySilly plugin cipher.

changeset:   15:9ffea19504e9
user:        Ralph Morelli <ram8647@gmail.com>
date:        Wed May 18 07:23:00 2011 -0400
summary:     Added Null cipher plugin.

(...)

The next step is to pull the changes we've made back into our original local repository.

$ cd ../hcryptoj-hg-repo
$ hg pull ../hcryptoj-hg-new-cipher/
pulling from ../hcryptoj-hg-new-cipher/
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 6 changes to 6 files
(run 'hg update' to get a working copy)

$ hg update
6 files updated, 0 files merged, 0 files removed, 0 files unresolved

$ hg tip
changeset:   16:85e65bf74d06
tag:         tip
user:        Ralph Morelli <ram8647@gmail.com>
date:        Wed May 18 07:37:39 2011 -0400
summary:     Added the MySilly plugin cipher.

The two repositories, the original one and its clone, are now in an identical state. You can confirm this by pushing back to the clone. What you should find is that there are no changes to be found:

hg push ../hcrypto-hg-new-cipher/
pushing to ../hcrypto-hg-cipher/
searching for changes
no changes found

Sharing the New Cipher

There are many ways to share changes in a code base. In the previous section we used push and pull to share a change between one repository and its clone.

In this section, we will use export to share our changes with other members of the lab.

After pulling your changes back to your hcrypto-hg-repo repository, it should look something like this:

hcryptoj-hg-repo rmorelli$ hg log
changeset:   16:4312316123e4
tag:         tip
user:        Ralph Morelli <ram8647@gmail.com>
date:        Wed May 18 11:06:29 2011 -0400
summary:     Added MySilly plugin cipher.

changeset:   15:62e937279a90
user:        Ralph Morelli <ram8647@gmail.com>
date:        Wed May 18 10:46:14 2011 -0400
summary:     Added Null cipher plugin.

changeset:   14:2f8f39e5be3a
user:        Ralph Morelli <ram8647@gmail.com>
date:        Wed May 18 06:37:04 2011 -0400
summary:     Updated the README file.

(...)

In this case we want to export the tip, as follows, saving it to a text file:

$ hg export tip > morellipatch.txt

$ hg status
? hcryptoj-hg-repo.jar
? morellipatch.txt
? src/plugins/NullEngine.java~
? src/plugins/NullKey.java~
? src/plugins/PluginProvider.java~
rmorelli-86396:hcryptoj-hg-repo rmorelli$ 

An exported patch file is in unified diff format. Here's what the patch looks like:

# HG changeset patch
# User Ralph Morelli <ram8647@gmail.com>
# Date 1305731189 14400
# Node ID 4312316123e4a50ace848ab46ddc6858683627d1
# Parent  62e937279a90b24c70529b7c79821a7e6acbfe47
Added MySilly plugin cipher.

diff -r 62e937279a90 -r 4312316123e4 classes/plugins/MySillyEngine.class
Binary file classes/plugins/MySillyEngine.class has changed
diff -r 62e937279a90 -r 4312316123e4 classes/plugins/MySillyKey.class
Binary file classes/plugins/MySillyKey.class has changed
diff -r 62e937279a90 -r 4312316123e4 classes/plugins/PluginProvider.class
Binary file classes/plugins/PluginProvider.class has changed
diff -r 62e937279a90 -r 4312316123e4 src/plugins/MySillyEngine.java
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/src/plugins/MySillyEngine.java    Wed May 18 11:06:29 2011 -0400
@@ -0,0 +1,60 @@
+/*
+ * File: MySillyEngine.java
+ * A plugin for CryptoToolJ.
+ */
+package plugins;
+
+import hcrypto.cipher.*;
+
+/**
+ * Implements a MySilly cipher for lowercase alphabet, az.
+ */
+
+
+public class MySillyEngine extends BlockCipher {

Lines marked with + are new lines. Lines marked with - are deleted lines.

Cleaning Up

Now that you have merged your new cipher back into your original working repository, you can delete the clone you created for this exercise, hcryptoj-hg-new-cipher. You're done with that task.

In the next tutorial, we will make additional changes to HcryptoJ using Eclipse.

Personal tools
NSF K-12