You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@trafodion.apache.org by su...@apache.org on 2016/10/27 15:13:31 UTC
[7/9] incubator-trafodion git commit: Updates to documentation
Updates to documentation
Project: http://git-wip-us.apache.org/repos/asf/incubator-trafodion/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-trafodion/commit/f7f1ee95
Tree: http://git-wip-us.apache.org/repos/asf/incubator-trafodion/tree/f7f1ee95
Diff: http://git-wip-us.apache.org/repos/asf/incubator-trafodion/diff/f7f1ee95
Branch: refs/heads/master
Commit: f7f1ee957ae07bd2cfbd38d6984876bbdedd6fed
Parents: f5179a1
Author: Anuradha Hegde <an...@esgyn.com>
Authored: Tue Oct 25 20:16:48 2016 +0000
Committer: Anuradha Hegde <an...@esgyn.com>
Committed: Tue Oct 25 20:16:48 2016 +0000
----------------------------------------------------------------------
core/rest/src/main/asciidoc/_chapters/apis.adoc | 124 +------------------
.../main/asciidoc/_chapters/architecture.adoc | 6 +-
.../main/asciidoc/_chapters/configuration.adoc | 26 ++--
.../asciidoc/_chapters/troubleshooting.adoc | 6 +-
.../main/java/org/trafodion/rest/Constants.java | 2 +-
.../asciidoc/_chapters/troubleshooting.adoc | 2 +-
6 files changed, 26 insertions(+), 140 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/f7f1ee95/core/rest/src/main/asciidoc/_chapters/apis.adoc
----------------------------------------------------------------------
diff --git a/core/rest/src/main/asciidoc/_chapters/apis.adoc b/core/rest/src/main/asciidoc/_chapters/apis.adoc
index 21980b4..ceffd32 100644
--- a/core/rest/src/main/asciidoc/_chapters/apis.adoc
+++ b/core/rest/src/main/asciidoc/_chapters/apis.adoc
@@ -31,133 +31,19 @@
:icons: font
:experimental:
-The terms "representational state transfer" and "REST" were introduced in 2000 in the doctoral dissertation of
-Roy Fielding, one of the principal authors of the Hypertext Transfer Protocol (HTTP) specification. In a nutshell
-
-A GET to an resource requests a copy of the information.
-
-A PUT to an resource replaces the resource.
-
-POST adds resources.
-
-DELETE eliminates resources.
-
[[rest]]
-== Resource Identifiers
+== REST APIs
+
The URIs for the REST-based web services have the following syntax:
http://{hostname:port}/{version}/{resourcepath}
The elements in this syntax are as follows:
- {hostname} - The http address of the service to get information about.
- Currently supported are the Trafodion DTM, RMS and DCS components.
- {version} - The version of the APIs. In this release, the version is v1.
- {resourcepath} - A path that defines a singleton resource or a collection of resources.
+ {hostname} - The http address of the service to get information about.
+ {version} - The version of the APIs. In this release, the version is v1.
+ {resourcepath} - A path that defines a singleton resource or a collection of resources.
-== HTTP Requests
-To invoke a REST API, your application calls an HTTP operation on the URI associated with a resource.
-
-.Headers
-This release ignores Accept and Accept-Encoding headers.
-
-== HTTP Responses
-The following sections describe the syntax of HTTP Responses.
-
-.Compression
-This release does not support compression.
-
-.Response Formats
-This release of the REST APIs supports responses in JSON format only.
-
-.Response Examples
-
-.JSON response with single resource
-
-HTTP Request:
-----
-GET http://{hostname:4200}/v1/servers
-----
-
-Response Status Line:
-----
-HTTP/1.1 200 OK
-----
-
-Response Header:
-----
- HTTP/1.1 200 OK
- Cache-Control: no-cache
- Content-Type: application/json
- Transfer-Encoding: chunked
-----
-
-Response Body:
-----
-{
- "STATE":"UP",
- "SUBSTATE":"OPERATIONAL",
- "PROCESSES":
- [
- {
- "PROCESS":"DTM",
- "CONFIGURED":2,
- "ACTUAL":2,
- "DOWN":""},
- {
- "PROCESS":"RMS",
- "CONFIGURED":4,
- "ACTUAL":4,
- "DOWN":""
- },
- {
- "PROCESS":"DCSMASTER",
- "CONFIGURED":2,
- "ACTUAL":2,
- "DOWN":""
- },
- {
- "PROCESS":"MXOSRVR",
- "CONFIGURED":4,
- "ACTUAL":4,
- "DOWN":""
- }
- ]
-}
-----
-
-.JSON response with Error response
-
-Here we request information about DCS client connections when DCS is stopped.
-
-HTTP Request:
-----
-GET http://{hostname:4200}/v1/servers/dcs/connections
-----
-
-Response Status Line:
-----
-HTTP/1.1 404 Not Found
-----
-
-Response Header:
-----
- HTTP/1.1 404 Not Found
- Content-Type: application/json
- Transfer-Encoding: chunked
-----
-
-Response Body:
-----
-{
- "RemoteException" : {
- "javaClassName" : "org.trafodion.rest.NotFoundException",
- "exception" : "NotFoundException",
- "message" : "DCS connection resources not found"
- }
-}
-----
-== Supported REST APIs
There are many ways/languages to use the REST API's. The following examples use the curl command line interface to do the REST calls.
[cols="15%,10%,40%,35%"]
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/f7f1ee95/core/rest/src/main/asciidoc/_chapters/architecture.adoc
----------------------------------------------------------------------
diff --git a/core/rest/src/main/asciidoc/_chapters/architecture.adoc b/core/rest/src/main/asciidoc/_chapters/architecture.adoc
index 0272cb3..7891223 100644
--- a/core/rest/src/main/asciidoc/_chapters/architecture.adoc
+++ b/core/rest/src/main/asciidoc/_chapters/architecture.adoc
@@ -64,7 +64,7 @@ HTTP and HTTPS requests. It's a 100% java implementation.
[[server-startup]]
=== Startup Behavior
-The server is started/stopped via the scripts found in the _/bin_ directory. During startup it opens a connection to ZooKeeper.
+The server is started/stopped via the scripts found in the _$REST_INSTALL_DIR/bin_ directory. During startup it opens a connection to ZooKeeper.
[[server-threads]]
=== Threads
@@ -76,11 +76,11 @@ is configured but this may be changed in the configuration by modifying the _res
[[server-processes-script-manager]]
==== ScriptManager
-The script manager thread is responsible for reading and compiling the Python scripts found in _/bin/scripts_ directory. It
+The script manager thread is responsible for reading and compiling the Python scripts found in _$REST_INSTALL_DIR/bin/scripts_ directory. It
can detect a change in any script found there. If any script changes it will recompile it.
==== JDBC Type 4
An embedded driver is available to execute Trafodion SQL queries by connecting to the DCS service.
==== JDBC Type 2
-An embedded driver is available to execute Trafodion SQL queries.
\ No newline at end of file
+An embedded driver is available to execute Trafodion SQL queries.
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/f7f1ee95/core/rest/src/main/asciidoc/_chapters/configuration.adoc
----------------------------------------------------------------------
diff --git a/core/rest/src/main/asciidoc/_chapters/configuration.adoc b/core/rest/src/main/asciidoc/_chapters/configuration.adoc
index 7b99b28..3ad7d3f 100644
--- a/core/rest/src/main/asciidoc/_chapters/configuration.adoc
+++ b/core/rest/src/main/asciidoc/_chapters/configuration.adoc
@@ -37,7 +37,7 @@ a thorough read of this chapter will help with non-standard configurations. Plea
requirements have been satisfied. Failure to do so will cause you grief debugging strange errors.
Trafodion REST uses the same configuration mechanism as Apache Hadoop.
-All configuration files are located in the _conf/_ directory.
+All configuration files are located in the _$REST_INSTALL_DIR/conf/_ directory.
[TIP]
====
@@ -48,7 +48,7 @@ ensure well-formedness of your document after an edit session.
.Keep Configuration In Sync Across the Cluster
[WARNING]
====
-After you make an edit to any configuration file, make sure you copy the content of the _conf_ directory to all nodes of the cluster.
+After you make an edit to any configuration file, make sure you copy the content of the _$REST_INSTALL_DIR/conf_ directory to all nodes of the cluster.
The server will not do this for you. Use +rsync+, +scp+, or another secure mechanism for copying the configuration files to your nodes.
A restart is needed for servers to pick up changes.
====
@@ -89,7 +89,7 @@ This `rest.zookeeper.quorum` property defaults to a single ensemble member at `l
== Configuration Files
=== _rest-site.xml_ and _rest-default.xml_
-You add site-specific configuration to the file _conf/rest-site.xml_. For the list of configurable properties,
+You add site-specific configuration to the file _$REST_INSTALL_DIR/conf/rest-site.xml_. For the list of configurable properties,
see <<rest_default_configurations,REST Default Configuration>> below or view the raw _rest-default.xml_ source
file in the source code at _src/main/resources_.
@@ -108,7 +108,7 @@ include::../../../../target/asciidoc/rest-default.adoc[]
=== _rest-env.sh_
Set server environment variables in this file. Examples include options to pass the JVM on start of
the server such as heap size and garbarge collector configs. You can also set configurations for server configuration, log directories,
-niceness, ssh options, where to locate process pid files, etc. Open the file at _conf/rest-env.sh_ and peruse its content.
+niceness, ssh options, where to locate process pid files, etc. Open the file at _$REST_INSTALL_DIR/conf/rest-env.sh_ and peruse its content.
Each option is fairly well documented. Add your own environment variables here if you want them read by the server on startup.
Changes here will require a restart for the server to notice the change.
@@ -121,7 +121,7 @@ Changes here will require a restart for the server to notice the change.
[[rest.keystore]]
=== _rest-keystore_
-This file will only be present if the property _rest.https.password_ has been set in _conf/rest-site.xml_.
+This file will only be present if the property _rest.https.password_ has been set in _$REST_INSTALL_DIR/conf/rest-site.xml_.
Please see <<important.configurations,Important Configurations>> for more detail.
[[important.configurations]]
@@ -133,7 +133,7 @@ The default value is 4200. This is the port the embedded Jetty server binds to
waiting for client HTTP connections. The value may need to be changed
if this port number conflicts with other ports in use on your cluster.
-To change this configuration, edit _conf/rest-site.xml_, copy the changed file around the cluster and restart.
+To change this configuration, edit _$REST_INSTALL_DIR/conf/rest-site.xml_, copy the changed file around the cluster and restart.
=== `rest.https.port`
The default value is 4201. This is the port the embedded Jetty server binds to
@@ -141,13 +141,13 @@ waiting for client HTTPS connections. The value may need to be changed
if this port number conflicts with other ports in use on your cluster.
=== `rest.ssl.password`
-This property is not present by default in _conf/rest-site.xml_. Typically the Trafodion
+This property is not present by default in _$REST_INSTALL_DIR/conf/rest-site.xml_. Typically the Trafodion
installer sets this property to an obfuscated password string. If this property is present then the server
will setup HTTPS in the embedded Jetty server. To create an obfuscated password for this property use
the following command:
----
-java -classpath $REST_HOME/lib/jetty-9.2.10.v20150310.jar:$REST_HOME/lib/jetty-util-9.2.10.v20150310.jar org.eclipse.jetty.util.security.Password}
+java -classpath $REST_INSTALL_DIR/lib/jetty-9.2.10.v20150310.jar:$REST_INSTALL_DIR/lib/jetty-util-9.2.10.v20150310.jar org.eclipse.jetty.util.security.Password}
----
The output of this command is similar to:
@@ -157,16 +157,16 @@ MD5:{obfuscated password string}
----
Copy/paste the entire string including "OBF:" into this property.
-The server will use this property when creating the _/conf/rest-keystore_ directory.
+The server will use this property when creating the _$REST_INSTALL_DIR/conf/rest-keystore_ directory.
-To change this configuration, edit _conf/rest-site.xml_, copy the changed file around the cluster and restart.
+To change this configuration, edit _$REST_INSTALL_DIR/conf/rest-site.xml_, copy the changed file around the cluster and restart.
[TIP]
====
To decrypt the obfuscated string in `rest.ssl.password` do the following:
----
-java -classpath $REST_HOME/lib/jetty-9.2.10.v20150310.jar:$REST_HOME/lib/jetty-util-9.2.10.v20150310.jar org.eclipse.jetty.util.security.Password {obfuscated password string}
+java -classpath $REST_INSTALL_DIR/lib/jetty-9.2.10.v20150310.jar:$REST_INSTALL_DIR/lib/jetty-util-9.2.10.v20150310.jar org.eclipse.jetty.util.security.Password {obfuscated password string}
----
The output of this command is similar to:
@@ -179,7 +179,7 @@ CRYPT:{obfuscated password string}
====
=== `dcs.master.port`
-The default value is 37800. This is the port the embedded JDBC Type 4 driver
+The default value is 23400. This is the port the embedded JDBC Type 4 driver
uses to connect to Trafodion DCS.
-To change this configuration, edit _conf/rest-site.xml_, copy the changed file around the cluster and restart.
+To change this configuration, edit _$REST_INSTALL_DIR/conf/rest-site.xml_, copy the changed file around the cluster and restart.
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/f7f1ee95/core/rest/src/main/asciidoc/_chapters/troubleshooting.adoc
----------------------------------------------------------------------
diff --git a/core/rest/src/main/asciidoc/_chapters/troubleshooting.adoc b/core/rest/src/main/asciidoc/_chapters/troubleshooting.adoc
index da08821..edc2182 100644
--- a/core/rest/src/main/asciidoc/_chapters/troubleshooting.adoc
+++ b/core/rest/src/main/asciidoc/_chapters/troubleshooting.adoc
@@ -34,8 +34,8 @@
== Logs
The key process logs are as follows...(replace <user> with the user that started the service, <instance> for the server instance and <hostname> for the machine name)
-* $REST_HOME/logs/rest-<user>-<instance>-rest-<hostname>.log
-* $REST_HOME/logs/rest-<user>-<instance>-rest-<hostname>.out
+* $REST_INSTALL_DIR/logs/rest-<user>-<instance>-rest-<hostname>.log
+* $REST_INSTALL_DIR/logs/rest-<user>-<instance>-rest-<hostname>.out
The logs are your best resource when troubleshooting the REST server.
@@ -70,4 +70,4 @@ The commands (and arguments) are:
addauth scheme auth
delete path [version]
setquota -n|-b val path
-----
\ No newline at end of file
+----
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/f7f1ee95/core/rest/src/main/java/org/trafodion/rest/Constants.java
----------------------------------------------------------------------
diff --git a/core/rest/src/main/java/org/trafodion/rest/Constants.java b/core/rest/src/main/java/org/trafodion/rest/Constants.java
index 52b210e..08fa1d7 100644
--- a/core/rest/src/main/java/org/trafodion/rest/Constants.java
+++ b/core/rest/src/main/java/org/trafodion/rest/Constants.java
@@ -48,7 +48,7 @@ public final class Constants {
public static final String DCS_MASTER_PORT = "dcs.master.port";
/** Default value for DCS master port */
- public static final int DEFAULT_DCS_MASTER_PORT = 37800;
+ public static final int DEFAULT_DCS_MASTER_PORT = 23400;
/** Name of ZooKeeper quorum configuration parameter. */
public static final String ZOOKEEPER_QUORUM = "rest.zookeeper.quorum";
http://git-wip-us.apache.org/repos/asf/incubator-trafodion/blob/f7f1ee95/dcs/src/main/asciidoc/_chapters/troubleshooting.adoc
----------------------------------------------------------------------
diff --git a/dcs/src/main/asciidoc/_chapters/troubleshooting.adoc b/dcs/src/main/asciidoc/_chapters/troubleshooting.adoc
index 9f94853..814e74b 100644
--- a/dcs/src/main/asciidoc/_chapters/troubleshooting.adoc
+++ b/dcs/src/main/asciidoc/_chapters/troubleshooting.adoc
@@ -159,7 +159,7 @@ On Linux cluster, if you run into issues please check dcs log files located in $
Validate that the interace is set up correctly. This command should only show one additional interface for HA configuration
----
-pdsh $MY_NODES "/sbin/ip addr show |grep 23400"
+pdsh $MY_NODES "sudo /sbin/ip addr show |grep 23400"
----
Validate to get the list of all the DcsMaster that are configured and started in the cluster