Allow superprojects to subscribe to submodules updates

Before discussing about the feature introduced in this commit,
let's discuss a little about the Submodule feature. It is a git
feature that allows an external repository to be attached inside
one repository at a specific path.

Imagine a repository called 'super' and another one called 'a'.
Also consider 'a' available in a running gerrit instance on "server".
With this feature, one could attach 'a' inside of 'super' repository
in path 'a' by executing following command when inside 'super':
"git submodule add ssh://server/a a".

Still considering above example, after its execution notice inside
'super' local repository the 'a' folder is considered a gitlink
to external repository 'a'. Also notice a file called .gitmodules
is created (it is a config file containing the subscription of 'a').
The "git submodule status" command provides the sha-1 each gitlink
points to in the external repository.

In the example provided, if 'a' is updated and 'super' is supposed
to see latest sha-1 (considering here 'a' has only the master branch),
one should then commit 'a' modified gitlink in 'super' project.
Actually it would not need to be even an external update, one could
move to 'a' folder (insider 'super'), modify its content, commit,
then move back to 'super' and commit 'a' gitlink.

The feature introduced in this commit allows superprojects to
subscribe to submodules updates.

When a commit is merged to a project, the commit content is scanned
to identify if it registers submodules (if the commit contains new
gitlinks and .gitmodules file with required info) and if so, a new
submodule subscription is registered.

When a new commit of a registered submodule is merged, gerrit
automatically updates the subscribers to the submodule with new
commit having the updated gitlinks.

The most notable benefit of the feature is to not require
to push/merge commits of super projects (subscribers) with gitlinks
whenever a project being a submodule is updated. It is only
required to push commits with gitlinks when they are created
(and in this case it is also required to push .gitmodules file).

Submodule subscription is actually the subscription of a submodule
project and one of its branches for a branch of a super project.
Whenever a submodule subscription is created, the user should certify
that the branch field is filled in the .gitmodules configuration file,
otherwise the subscriptions are not registered in gerrit. It is not
automatically filled by git submodule command. Its value should indicate
the branch of submodule project that when updated will trigger
automatic update of its registered gitlink. The branch value
could be '.' if the submodule project branch has the same name that
the destination branch of commit having gitlinks/.gitmodules file.

Since it manages subscriptions in the branch scope, we could have
a scenario having a project called 'super' having a branch 'integration'
subscribed to a project called 'a' in branch 'integration', and also
having same 'super' project but in branch 'dev' subscribed to the 'a'
project in a branch called 'local-dev'.

If one does not want to have use of this feature, (s)he should
not add the branch field in an added submodule section of .gitmodules
file. If one have added a submodule subscription and want to drop it,
it is required to merge a commit updating subscribed super project/branch
removing the gitlink and the submodule section of .gitmodules file.

The branch field of a submodule section is a custom git submodule
feature introduced by this one and for gerrit use. One should always
certify to fill it by editing .gitmodules file after adding
submodules to a super project, if it is the intention to make use of
the gerrit feature introduced here.

The feature also requires the canonical web url provided
in the gerrit configuration file. It will automatically updates
only the subscribers of project urls of the running server (the one
described in canonical web url value).

Considering the functionalities introduced in this feature, we have
actually an option to the current way Android platform code is handled
(using manifest.xml files). And it offers the benefit of not
requiring users to introduce commits in the super project (platform
repository considering Android source code example) and not
using the repo tool.

Also notice that the feature makes possible to have recursive update:
a 'super' project could be the subscriber of an 'a' project, and the
'a' project could be the subscriber of a 'a-subproject' project.

Change-Id: Id067e85d914e13324f1f28418233cc96a60e3ab2

gerrit-server/src/main/java/com/google/gerrit/server/git/SubmoduleException.java

@@ -0,0 +1,28 @@
+// Copyright (C) 2011 The Android Open Source Project
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+// http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package com.google.gerrit.server.git;
+
+/** Indicates the gitlink's update cannot be processed at this time. */
+class SubmoduleException extends Exception {
+  private static final long serialVersionUID = 1L;
+
+  SubmoduleException(final String msg) {
+    super(msg, null);
+  }
+
+  SubmoduleException(final String msg, final Throwable why) {
+    super(msg, why);
+  }
+}