opendev/gerrit
Code Issues Proposed changes

Add new SSH command to search in Gerrit documentation index

Browse Source 
$>ssh review gerrit apropos capabilities
Gerrit Code Review - /config/ REST API:
http://localhost:8080/Documentation/rest-api-config.html

Gerrit Code Review - /accounts/ REST API:
http://localhost:8080/Documentation/rest-api-accounts.html

Gerrit Code Review - Project Configuration File Format:
http://localhost:8080/Documentation/config-project-config.html

Gerrit Code Review - Access Controls:
http://localhost:8080/Documentation/access-control.html

Gerrit Code Review - Plugin Development:
http://localhost:8080/Documentation/dev-plugins.html

Gerrit Code Review - REST API:
http://localhost:8080/Documentation/rest-api.html

Gerrit Code Review - /access/ REST API:
http://localhost:8080/Documentation/rest-api-access.html

Change-Id: I26d067e8e6e5056a53d25457361b079e437f4fd0
This commit is contained in:
David Ostrovsky 2013-10-19 10:38:50 +02:00
parent 36599f67ee
commit 1f04bca4bf
12 changed files with 294 additions and 144 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

63
Documentation/cmd-apropos.txt Normal file
View File

@ -0,0 +1,63 @@
gerrit apropos
==============
NAME
----
gerrit apropos - Search Gerrit documentation index
SYNOPSIS
--------
[verse]
'ssh' -p <port> <host> 'gerrit apropos'
<query>
DESCRIPTION
-----------
Queries the documentation index and returns results with the title and URL
from the matched documents.
ACCESS
------
Any user who has configured an SSH key.
SCRIPTING
---------
This command is intended to be used in scripts.
Note: this feature is only available if documentation index was built.
EXAMPLES
--------
=====
$ ssh -p 29418 review.example.com gerrit apropos capabilities
Gerrit Code Review - /config/ REST API:
http://localhost:8080/Documentation/rest-api-config.html
Gerrit Code Review - /accounts/ REST API:
http://localhost:8080/Documentation/rest-api-accounts.html
Gerrit Code Review - Project Configuration File Format:
http://localhost:8080/Documentation/config-project-config.html
Gerrit Code Review - Access Controls:
http://localhost:8080/Documentation/access-control.html
Gerrit Code Review - Plugin Development:
http://localhost:8080/Documentation/dev-plugins.html
Gerrit Code Review - REST API:
http://localhost:8080/Documentation/rest-api.html
Gerrit Code Review - /access/ REST API:
http://localhost:8080/Documentation/rest-api-access.html
=====
SEE ALSO
--------
* link:access-control.html[Access Controls]
GERRIT
------
Part of link:index.html[Gerrit Code Review]

3
Documentation/cmd-index.txt
View File

@ -51,6 +51,9 @@ see link:user-upload.html#test_ssh[Testing Your SSH Connection].
[[user_commands]]User Commands
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
link:cmd-apropos.html[gerrit apropos]::
Search Gerrit documentation index.
'gerrit approve'::
'Deprecated alias for `gerrit review`.'

13
gerrit-httpd/BUCK
View File

@ -1,24 +1,13 @@
CONSTANTS_SRC = [
'src/main/java/com/google/gerrit/httpd/rpc/doc/Constants.java',
]
SRCS = glob(
['src/main/java/**/*.java'],
excludes = CONSTANTS_SRC,
)
RESOURCES = glob(['src/main/resources/**/*'])
java_library2(
name = 'constants',
srcs = CONSTANTS_SRC,
visibility = ['PUBLIC'],
)
java_library2(
name = 'httpd',
srcs = SRCS,
resources = RESOURCES,
deps = [
':constants',
'//gerrit-antlr:query_exception',
'//gerrit-common:server',
'//gerrit-extension-api:api',
@ -43,9 +32,7 @@ java_library2(
'//lib/jgit:jgit',
'//lib/jgit:jgit-servlet',
'//lib/log:api',
'//lib/lucene:analyzers-common',
'//lib/lucene:core',
'//lib/lucene:query-parser',
],
compile_deps = ['//lib:servlet-api-3_0'],
visibility = ['PUBLIC'],

131
gerrit-httpd/src/main/java/com/google/gerrit/httpd/rpc/doc/QueryDocumentationFilter.java
View File

@ -16,35 +16,16 @@ package com.google.gerrit.httpd.rpc.doc;
import com.google.common.base.Strings;
import com.google.common.collect.LinkedHashMultimap;
import com.google.common.collect.Lists;
import com.google.common.collect.Multimap;
import com.google.gerrit.httpd.restapi.RestApiServlet;
import com.google.gerrit.server.documentation.QueryDocumentationExecutor;
import com.google.gerrit.server.documentation.QueryDocumentationExecutor.DocQueryException;
import com.google.gerrit.server.documentation.QueryDocumentationExecutor.DocResult;
import com.google.inject.Inject;
import com.google.inject.Singleton;
import org.apache.lucene.analysis.standard.StandardAnalyzer;
import org.apache.lucene.document.Document;
import org.apache.lucene.index.DirectoryReader;
import org.apache.lucene.index.IndexReader;
import org.apache.lucene.queryparser.classic.ParseException;
import org.apache.lucene.queryparser.classic.QueryParser;
import org.apache.lucene.search.IndexSearcher;
import org.apache.lucene.search.Query;
import org.apache.lucene.search.ScoreDoc;
import org.apache.lucene.search.TopDocs;
import org.apache.lucene.store.Directory;
import org.apache.lucene.store.IndexOutput;
import org.apache.lucene.store.RAMDirectory;
import org.apache.lucene.util.Version;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.io.IOException;
import java.io.InputStream;
import java.util.List;
import java.util.zip.ZipEntry;
import java.util.zip.ZipInputStream;
import javax.servlet.Filter;
import javax.servlet.FilterChain;
@ -57,43 +38,15 @@ import javax.servlet.http.HttpServletResponse;
@Singleton
public class QueryDocumentationFilter implements Filter {
private static final Logger log =
LoggerFactory.getLogger(QueryDocumentationFilter.class);
private static final String INDEX_PATH = "index.zip";
private static final Version LUCENE_VERSION = Version.LUCENE_44;
private IndexSearcher searcher;
private QueryParser parser;
protected static class DocResult {
public String title;
public String url;
public String content;
}
private final QueryDocumentationExecutor searcher;
@Inject
QueryDocumentationFilter() {
QueryDocumentationFilter(QueryDocumentationExecutor searcher) {
this.searcher = searcher;
}
@Override
public void init(FilterConfig filterConfig) {
try {
Directory dir = readIndexDirectory();
if (dir == null) {
searcher = null;
parser = null;
return;
}
IndexReader reader = DirectoryReader.open(dir);
searcher = new IndexSearcher(reader);
StandardAnalyzer analyzer = new StandardAnalyzer(LUCENE_VERSION);
parser = new QueryParser(LUCENE_VERSION, Constants.DOC_FIELD, analyzer);
} catch (IOException e) {
log.error("Cannot initialize documentation full text index", e);
searcher = null;
parser = null;
}
}
@Override
@ -108,7 +61,7 @@ public class QueryDocumentationFilter implements Filter {
&& !Strings.isNullOrEmpty(req.getParameter("q"))) {
HttpServletResponse rsp = (HttpServletResponse) response;
try {
List<DocResult> result = doQuery(request.getParameter("q"));
List<DocResult> result = searcher.doQuery(request.getParameter("q"));
Multimap<String, String> config = LinkedHashMultimap.create();
RestApiServlet.replyJson(req, rsp, config, result);
} catch (DocQueryException e) {
@ -118,74 +71,4 @@ public class QueryDocumentationFilter implements Filter {
chain.doFilter(request, response);
}
}
private List<DocResult> doQuery(String q) throws DocQueryException {
if (parser == null || searcher == null) {
throw new DocQueryException("Not initialized");
}
try {
Query query = parser.parse(q);
TopDocs results = searcher.search(query, Integer.MAX_VALUE);
ScoreDoc[] hits = results.scoreDocs;
int totalHits = results.totalHits;
List<DocResult> out = Lists.newArrayListWithCapacity(totalHits);
for (int i = 0; i < totalHits; i++) {
DocResult result = new DocResult();
Document doc = searcher.doc(hits[i].doc);
result.url = doc.get(Constants.URL_FIELD);
result.title = doc.get(Constants.TITLE_FIELD);
out.add(result);
}
return out;
} catch (IOException e) {
throw new DocQueryException(e);
} catch (ParseException e) {
throw new DocQueryException(e);
}
}
protected Directory readIndexDirectory() throws IOException {
Directory dir = new RAMDirectory();
byte[] buffer = new byte[4096];
InputStream index =
QueryDocumentationFilter.class.getClassLoader().getResourceAsStream(INDEX_PATH);
if (index == null) {
log.warn("No index available");
return null;
}
ZipInputStream zip = new ZipInputStream(index);
try {
ZipEntry entry;
while ((entry = zip.getNextEntry()) != null) {
IndexOutput out = dir.createOutput(entry.getName(), null);
int count;
while ((count = zip.read(buffer)) != -1) {
out.writeBytes(buffer, count);
}
out.close();
}
} finally {
zip.close();
}
// We must NOT call dir.close() here, as DirectoryReader.open() expects an opened directory.
return dir;
}
private static class DocQueryException extends Exception {
public DocQueryException() {
}
public DocQueryException(String msg) {
super(msg);
}
public DocQueryException(String msg, Throwable e) {
super(msg, e);
}
public DocQueryException(Throwable e) {
super(e);
}
}
}

22
gerrit-server/BUCK
View File

@ -1,15 +1,28 @@
CONSTANTS_SRC = [
'src/main/java/com/google/gerrit/server/documentation/Constants.java',
]
SRCS = glob([
'src/main/java/**/*.java',
'src/test/java/com/google/gerrit/server/project/Util.java'
])
'src/main/java/**/*.java',
'src/test/java/com/google/gerrit/server/project/Util.java',
],
excludes = CONSTANTS_SRC,
)
RESOURCES = glob(['src/main/resources/**/*'])
java_library2(
name = 'constants',
srcs = CONSTANTS_SRC,
visibility = ['PUBLIC'],
)
# TODO(sop) break up gerrit-server java_library(), its too big
java_library2(
name = 'server',
srcs = SRCS,
resources = RESOURCES,
deps = [
':constants',
'//gerrit-antlr:query_exception',
'//gerrit-antlr:query_parser',
'//gerrit-common:server',
@ -48,6 +61,9 @@ java_library2(
'//lib/joda:joda-time',
'//lib/log:api',
'//lib/prolog:prolog-cafe',
'//lib/lucene:analyzers-common',
'//lib/lucene:core',
'//lib/lucene:query-parser',
],
compile_deps = [
'//lib/bouncycastle:bcprov',

2
gerrit-server/src/main/java/com/google/gerrit/server/config/GerritGlobalModule.java
View File

@ -67,6 +67,7 @@ import com.google.gerrit.server.auth.AuthBackend;
import com.google.gerrit.server.auth.UniversalAuthBackend;
import com.google.gerrit.server.avatar.AvatarProvider;
import com.google.gerrit.server.cache.CacheRemovalListener;
import com.google.gerrit.server.documentation.QueryDocumentationExecutor;
import com.google.gerrit.server.events.EventFactory;
import com.google.gerrit.server.extensions.events.GitReferenceUpdated;
import com.google.gerrit.server.git.ChangeCache;
@ -135,6 +136,7 @@ public class GerritGlobalModule extends FactoryModule {
protected void configure() {
bind(EmailExpander.class).toProvider(EmailExpanderProvider.class).in(
SINGLETON);
bind(QueryDocumentationExecutor.class).in(SINGLETON);
bind(IdGenerator.class);
bind(RulesCache.class);

2
gerrit-httpd/src/main/java/com/google/gerrit/httpd/rpc/doc/Constants.java → gerrit-server/src/main/java/com/google/gerrit/server/documentation/Constants.java
View File

@ -12,7 +12,7 @@
// See the License for the specific language governing permissions and
// limitations under the License.
package com.google.gerrit.httpd.rpc.doc;
package com.google.gerrit.server.documentation;
public class Constants {

150
gerrit-server/src/main/java/com/google/gerrit/server/documentation/QueryDocumentationExecutor.java Normal file
View File

@ -0,0 +1,150 @@
// Copyright (C) 2013 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.documentation;
import com.google.common.collect.Lists;
import com.google.inject.Inject;
import org.apache.lucene.analysis.standard.StandardAnalyzer;
import org.apache.lucene.document.Document;
import org.apache.lucene.index.DirectoryReader;
import org.apache.lucene.index.IndexReader;
import org.apache.lucene.queryparser.classic.ParseException;
import org.apache.lucene.queryparser.classic.QueryParser;
import org.apache.lucene.search.IndexSearcher;
import org.apache.lucene.search.Query;
import org.apache.lucene.search.ScoreDoc;
import org.apache.lucene.search.TopDocs;
import org.apache.lucene.store.Directory;
import org.apache.lucene.store.IndexOutput;
import org.apache.lucene.store.RAMDirectory;
import org.apache.lucene.util.Version;
import org.slf4j.Logger;
import org.slf4j.LoggerFactory;
import java.io.IOException;
import java.io.InputStream;
import java.util.List;
import java.util.zip.ZipEntry;
import java.util.zip.ZipInputStream;
public class QueryDocumentationExecutor {
private static final Logger log =
LoggerFactory.getLogger(QueryDocumentationExecutor.class);
private static final String INDEX_PATH = "index.zip";
private static final Version LUCENE_VERSION = Version.LUCENE_44;
private IndexSearcher searcher;
private QueryParser parser;
public static class DocResult {
public String title;
public String url;
public String content;
}
@Inject
public QueryDocumentationExecutor() {
try {
Directory dir = readIndexDirectory();
if (dir == null) {
searcher = null;
parser = null;
return;
}
IndexReader reader = DirectoryReader.open(dir);
searcher = new IndexSearcher(reader);
StandardAnalyzer analyzer = new StandardAnalyzer(LUCENE_VERSION);
parser = new QueryParser(LUCENE_VERSION, Constants.DOC_FIELD, analyzer);
} catch (IOException e) {
log.error("Cannot initialize documentation full text index", e);
searcher = null;
parser = null;
}
}
public List<DocResult> doQuery(String q) throws DocQueryException {
if (parser == null || searcher == null) {
throw new DocQueryException("Documentation search not available");
}
try {
Query query = parser.parse(q);
TopDocs results = searcher.search(query, Integer.MAX_VALUE);
ScoreDoc[] hits = results.scoreDocs;
int totalHits = results.totalHits;
List<DocResult> out = Lists.newArrayListWithCapacity(totalHits);
for (int i = 0; i < totalHits; i++) {
DocResult result = new DocResult();
Document doc = searcher.doc(hits[i].doc);
result.url = doc.get(Constants.URL_FIELD);
result.title = doc.get(Constants.TITLE_FIELD);
out.add(result);
}
return out;
} catch (IOException e) {
throw new DocQueryException(e);
} catch (ParseException e) {
throw new DocQueryException(e);
}
}
protected Directory readIndexDirectory() throws IOException {
Directory dir = new RAMDirectory();
byte[] buffer = new byte[4096];
InputStream index =
QueryDocumentationExecutor.class.getClassLoader()
.getResourceAsStream(INDEX_PATH);
if (index == null) {
log.warn("No index available");
return null;
}
ZipInputStream zip = new ZipInputStream(index);
try {
ZipEntry entry;
while ((entry = zip.getNextEntry()) != null) {
IndexOutput out = dir.createOutput(entry.getName(), null);
int count;
while ((count = zip.read(buffer)) != -1) {
out.writeBytes(buffer, count);
}
out.close();
}
} finally {
zip.close();
}
// We must NOT call dir.close() here, as DirectoryReader.open() expects an opened directory.
return dir;
}
@SuppressWarnings("serial")
public static class DocQueryException extends Exception {
DocQueryException() {
}
DocQueryException(String msg) {
super(msg);
}
DocQueryException(String msg, Throwable e) {
super(msg, e);
}
DocQueryException(Throwable e) {
super(e);
}
}
}

46
gerrit-sshd/src/main/java/com/google/gerrit/sshd/commands/AproposCommand.java Normal file
View File

@ -0,0 +1,46 @@
// Copyright (C) 2013 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.sshd.commands;
import com.google.gerrit.server.config.CanonicalWebUrl;
import com.google.gerrit.server.documentation.QueryDocumentationExecutor;
import com.google.gerrit.server.documentation.QueryDocumentationExecutor.DocResult;
import com.google.gerrit.sshd.CommandMetaData;
import com.google.gerrit.sshd.SshCommand;
import com.google.inject.Inject;
import org.kohsuke.args4j.Argument;
import java.util.List;
@CommandMetaData(name = "apropos", description = "Search in Gerrit documentation")
final class AproposCommand extends SshCommand {
@Inject
private QueryDocumentationExecutor searcher;
@Inject
@CanonicalWebUrl String url;
@Argument(index=0, required = true, metaVar = "QUERY")
private String q;
@Override
public void run() throws Exception {
List<QueryDocumentationExecutor.DocResult> res = searcher.doQuery(q);
for (DocResult docResult : res) {
stdout.println(String.format("%s:\n%s%s\n", docResult.title, url,
docResult.url));
}
}
}

1
gerrit-sshd/src/main/java/com/google/gerrit/sshd/commands/DefaultCommandModule.java
View File

@ -36,6 +36,7 @@ public class DefaultCommandModule extends CommandModule {
// SlaveCommandModule.
command(gerrit).toProvider(new DispatchCommandProvider(gerrit));
command(gerrit, AproposCommand.class);
command(gerrit, BanCommitCommand.class);
command(gerrit, FlushCaches.class);
command(gerrit, ListProjectsCommand.class);

2
lib/asciidoctor/BUCK
View File

@ -31,7 +31,7 @@ java_library(
srcs = ['java/DocIndexer.java'],
deps = [
':asciidoc_lib',
'//gerrit-httpd:constants',
'//gerrit-server:constants',
'//lib:args4j',
'//lib:guava',
'//lib/lucene:analyzers-common',

3
lib/asciidoctor/java/DocIndexer.java
View File

@ -13,7 +13,7 @@
// limitations under the License.
import com.google.common.io.Files;
import com.google.gerrit.httpd.rpc.doc.Constants;
import com.google.gerrit.server.documentation.Constants;
import org.apache.lucene.analysis.standard.StandardAnalyzer;
import org.apache.lucene.analysis.util.CharArraySet;
@ -26,7 +26,6 @@ import org.apache.lucene.index.IndexWriterConfig;
import org.apache.lucene.index.IndexWriterConfig.OpenMode;
import org.apache.lucene.store.NIOFSDirectory;
import org.apache.lucene.util.Version;
import org.kohsuke.args4j.Argument;
import org.kohsuke.args4j.CmdLineException;
import org.kohsuke.args4j.CmdLineParser;