Merge pull request #563 from GoogleCloudPlatform/discovery-endpoints-migration

Update Endpoints Migration sample

Author: frankyn

appengine/endpoints-frameworks-v2/README.md

@@ -3,10 +3,10 @@
 This directory contains Google Cloud Endpoints Frameworks for App Engine for
 App Engine Standard samples. The [`backend/`](backend/) directory contains the
 sample code for the [quickstart][4] for Cloud Endpoints Frameworks on App Engine
-using an OpenAPI development process. The [`discovery/`](discovery/) directory
-contains the sample code for [migrated][2] prior version of [Cloud Endpoints
-Frameworks][1] project to the new [Cloud Endpoints Frameworks for App Engine][8]
-using a discovery document development process.
+using an OpenAPI development process. The [`migration-example/`](migration-example/) directory
+contains the sample code for a [migrated][2] version of the [Cloud Endpoints
+Frameworks][1] sample project to the new [Cloud Endpoints Frameworks for App Engine][8]
+development process.
 
 The new Google Cloud Endpoints Frameworks for App Engine provides
 [additional functionality][3] using OpenAPI which may require payment.

appengine/endpoints-frameworks-v2/discovery/README.md renamed to appengine/endpoints-frameworks-v2/migration-example/README.md

@@ -1,16 +1,15 @@
-# Hello World Google Cloud Endpoints for App Engine with a discovery document
+# Hello World Google Cloud Endpoints for App Engine
 
 This sample provides an example of a [migration][7] from the prior version of
-[Google Cloud Endpoints Frameworks][3] to new [Google Cloud Endpoints Frameworks for App Engine][8]
-while still using a discovery document. This sample contains comments of how to 
-use the prior Endpoints Frameworks as well. For clarity, the prior Endpoints
-Frameworks and the new Endpoints Frameworks are denoted as Endpoints Frameworks v1.0
-and Endpoints Frameworks v2.0 respectively.
+[Google Cloud Endpoints Frameworks][3] to new [Google Cloud Endpoints Frameworks for App Engine][8].
+This sample contains comments of how to use the prior Endpoints Frameworks as
+well. For clarity, the prior Endpoints Frameworks and the new Endpoints
+Frameworks are denoted as Endpoints Frameworks v1.0 and Endpoints Frameworks
+v2.0, respectively.
 
 Google Cloud Endpoints Frameworks v2.0 provides new functionality which may
-require payment and uses an OpenAPI specification instead of the discovery document.
-The OpenAPI development process is explained [here][8] and a quickstart is
-provided [here][9].
+require payment and uses an OpenAPI specification. The OpenAPI development
+process is explained [here][8] and a quickstart is provided [here][9].
 
 ## Products
 - [Google App Engine Standard][1]
@@ -30,23 +29,27 @@ provided [here][9].
 1. [Optional]: User Authenticating with Google Accounts in Web Clients
 
     1. Update the `WEB_CLIENT_ID` in [Constants.java](src/main/java/com/example/helloendpoints/Constants.java)
-      to reflect the web client ID you have registered in the [Credentials on Developers Console for OAuth 2.0 client IDs][6].
+      to reflect the web client ID you have registered in the
+      [Credentials on Developers Console for OAuth 2.0 client IDs][6].
 
-    1. Update the value of `google.devrel.samples.helloendpoints.CLIENT_ID` in [base.js](src/main/webapp/js/base.js)
-       to reflect the web client ID you have registered in the [Credentials on Developers Console for OAuth 2.0 client IDs][6].
+    1. Update the value of `google.devrel.samples.helloendpoints.CLIENT_ID` in
+       [base.js](src/main/webapp/js/base.js) to reflect the web client ID you
+       have registered in the
+       [Credentials on Developers Console for OAuth 2.0 client IDs][6].
 
 1. [Optional]: User Authenticating with Google Accounts in other Applications Types
 
     - Inside [Constants.java](src/main/java/com/example/helloendpoints/Constants.java) you will find placeholders for Android
-      and iOS applications using Google Accounts client IDs registered in the
+      applications using Google Accounts client IDs registered in the
       [Credentials on Developers Console for OAuth 2.0 client IDs][6].
 
-    - These client IDs are used when defining annotation for this sample API found in [Greetings.java](src/main/java/com/example/helloendpoints/Greetings.java).
+    - These client IDs are used when defining annotation for this sample API
+      found in [Greetings.java](src/main/java/com/example/helloendpoints/Greetings.java).
 
     - You can read more about different user authentication supported [here][12].
 
 
-1. [Optional]: Use Cloud Endpoints Frameworks v2.0 Maven and Gradle discovery and
+1. [Optional]: Use Cloud Endpoints Frameworks v2.0 Maven and Gradle
    client library generation plugins with Cloud Endpoints Frameworks v1.0.
 
     - Uncomment `Endpoints Frameworks v1.0` sections and comment
@@ -62,57 +65,61 @@ provided [here][9].
 
 ###  Maven
 
-1. Build a fresh binary with
+1. Build a fresh binary by using:
 
     `mvn clean compile`
 
-1. Run the application locally at [localhost:8080][5] with
+1. Run the application locally at [http://localhost:8080][5] by using:
 
     `mvn appengine:run`
 
-1. Generate the client library in a zip file named `helloworld-v1-java.zip` with
+1. Explore local server's API explorer by browsing to:
+
+    [http://localhost:8080/_ah/api/explorer][13]
+
+1. Generate the client library located at `target/client-libs/helloworld-v1-java.zip`
+   by using:
 
     `mvn endpoints-framework:clientLibs`
 
-1. Deploy your application to Google App Engine with
+1. Deploy your application to Google App Engine by using:
 
     `mvn appengine:deploy`
 
 ### Gradle
 
-1. Build a fresh binary with
+1. Build a fresh binary by using:
 
     `gradle clean compileJava`
 
-1. Run the application locally at [localhost:8080][5] with
+1. Run the application locally at [http://localhost:8080][5] by using:
 
     `gradle appengineRun`
 
-1. Generate the client library in a zip file named `helloworld-v1-java.zip` with
+1. Explore local server's API explorer by browsing to:
 
-    `gradle endpointsClientLibs`
+    [http://localhost:8080/_ah/api/explorer][13]
 
-1. Deploy your application to Google App Engine with
+1. Generate the client library located at `build/endpointsClientLibs/helloworld-v1-java.zip`
+   by using:
 
-    `gradle appengineDeploy`
+    `gradle endpointsClientLibs`
 
-## Known issues
+1. Deploy your application to Google App Engine by using:
 
-There's a [bug][13] where `<version>1</version>` is required in the
-[appengine-web.xml](src/main/webapp/WEB-INF/appengine-web.xml) to run
-this sample locally. This will become optional in the near future.
+    `gradle appengineDeploy`
 
 
 [1]: https://cloud.google.com/appengine/docs/java/
 [2]: http://java.com/en/
 [3]: https://cloud.google.com/appengine/docs/java/endpoints/
 [4]: https://cloud.google.com/appengine/docs/java/tools/maven
-[5]: https://localhost:8080/
+[5]: http://localhost:8080/
 [6]: https://console.developers.google.com/project/_/apiui/credential
 [7]: https://cloud.google.com/appengine/docs/java/endpoints/migrating
 [8]: https://cloud.google.com/endpoints/docs/frameworks/java/about-cloud-endpoints-frameworks
 [9]: https://cloud.google.com/endpoints/docs/frameworks/java/quickstart-frameworks-java
 [10]: https://github.com/GoogleCloudPlatform/endpoints-framework-maven-plugin
 [11]: https://github.com/GoogleCloudPlatform/endpoints-framework-gradle-plugin
 [12]: https://cloud.google.com/endpoints/docs/authenticating-users-frameworks
-[13]: https://github.com/cloudendpoints/endpoints-java/issues/43
+[13]: http://localhost:8080/_ah/api/explorer

appengine/endpoints-frameworks-v2/discovery/build.gradle renamed to appengine/endpoints-frameworks-v2/migration-example/build.gradle

@@ -12,16 +12,21 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
+// [START buildscript]
 buildscript {    // Configuration for building
   repositories {
     mavenCentral()
     jcenter()    // Bintray's repository - a fast Maven Central mirror & more
   }
   dependencies {
-    classpath 'com.google.cloud.tools:appengine-gradle-plugin:+'    // latest App Engine Gradle tasks
-    classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:+'
+    // App Engine Gradle plugin
+    classpath 'com.google.cloud.tools:appengine-gradle-plugin:1.1.1'
+
+    // Endpoints Frameworks Gradle plugin
+    classpath 'com.google.cloud.tools:endpoints-framework-gradle-plugin:1.0.0-beta6'
   }
 }
+// [END buildscript]
 
 repositories {   // repositories for Jar's you access in your code
   mavenCentral()
@@ -30,8 +35,14 @@ repositories {   // repositories for Jar's you access in your code
 
 apply plugin: 'java'                              // standard Java tasks
 apply plugin: 'war'                               // standard Web Archive plugin
+
+// [START apply_appengine]
 apply plugin: 'com.google.cloud.tools.appengine'  // App Engine tasks
+// [END apply_appengine]
+
+// [START apply_endpoints-framework-server]
 apply plugin: 'com.google.cloud.tools.endpoints-framework-server'
+// [END apply_endpoints-framework-server]
 
 dependencies {
   providedCompile group: 'javax.servlet', name: 'servlet-api', version:'2.5'
@@ -43,7 +54,9 @@ dependencies {
   // End of Endpoints Frameworks v1.0
 
   // Endpoints Frameworks v2.0
-  compile "com.google.endpoints:endpoints-framework:+"
+  // [START endpoints-tools]
+  compile group: 'com.google.endpoints', name: 'endpoints-framework-tools', version: '2.0.4'
+  // [END endpoints-tools]
   // End of Endpoints Frameworks v2.0
 }
 
@@ -58,8 +71,14 @@ appengine {  // App Engine tasks configuration
   }
 }
 
-group   = "com.example.helloendpoints"        // Generated output GroupId
-version = "1"        // Version in generated output
+/* [START endpoints-server]
+endpointsServer {
+  // Endpoints Framework Plugin server-side configuration
+}
+[END endpoints-server] */
+
+group   = 'com.example.helloendpoints' // Generated output GroupId
+version = '1'                          // Version in generated output
 
 sourceCompatibility = 1.7     // App Engine Standard uses Java 7
 targetCompatibility = 1.7     // App Engine Standard uses Java 7

appengine/endpoints-frameworks-v2/discovery/gradle/wrapper/gradle-wrapper.properties renamed to appengine/endpoints-frameworks-v2/migration-example/gradle/wrapper/gradle-wrapper.properties

@@ -30,14 +30,6 @@ limitations under the License.
     </parent>
 
     <properties>
-        <!-- Uncomment to use Endpoints Frameworks v1.0 -->
-        <!--
-        <appengine.endpoints.version>1.9.48</appengine.endpoints.version>
-        -->
-        <!-- End of Endpoints Frameworks v1.0 -->
-        <appengine.maven.version>1.0.0</appengine.maven.version>
-        <endpoints.maven.plugin.version>1.0.0-beta2</endpoints.maven.plugin.version>
-        <endpoints.framework.version>2.0.0-beta.12</endpoints.framework.version>
         <javax.inject.version>1</javax.inject.version>
         <maven.compiler.source>1.7</maven.compiler.source>
         <maven.compiler.target>1.7</maven.compiler.target>
@@ -53,18 +45,24 @@ limitations under the License.
     <dependencies>
         <!-- Compile/runtime dependencies -->
         <!-- Uncomment to use Endpoints Frameworks v1.0 -->
-        <!--<dependency>
+        <!--
+        [START appengine-endpoints]
+        <dependency>
               <groupId>com.google.appengine</groupId>
               <artifactId>appengine-endpoints</artifactId>
-              <version>${appengine.endpoints.version}</version>
-        </dependency>-->
+              <version>1.9.48</version>
+        </dependency>
+        [END appengine-endpoints]
+        -->
         <!-- End of Endpoints Frameworks v1.0 -->
         <!-- Endpoints Frameworks v2.0 -->
+        <!-- [START endpoints-frameworks] -->
         <dependency>
             <groupId>com.google.endpoints</groupId>
             <artifactId>endpoints-framework</artifactId>
-            <version>${endpoints.framework.version}</version>
+            <version>2.0.4</version>
         </dependency>
+        <!-- [END endpoints-frameworks] -->
         <!-- End of Endpoints Frameworks v2.0 -->
         <dependency>
             <groupId>javax.servlet</groupId>
@@ -83,31 +81,26 @@ limitations under the License.
         <!-- for hot reload of the web application-->
         <outputDirectory>${project.build.directory}/${project.build.finalName}/WEB-INF/classes</outputDirectory>
         <plugins>
+            <!-- [START appengine-plugin] -->
             <plugin>
                 <groupId>com.google.cloud.tools</groupId>
                 <artifactId>appengine-maven-plugin</artifactId>
-                <version>${appengine.maven.version}</version>
+                <version>1.2.1</version>
                 <configuration>
                     <!-- deploy configuration -->
                 </configuration>
             </plugin>
+            <!-- [END appengine-plugin] -->
+            <!-- [START endpoints-frameworks-plugin] -->
             <plugin>
                 <groupId>com.google.cloud.tools</groupId>
                 <artifactId>endpoints-framework-maven-plugin</artifactId>
-                <version>${endpoints.maven.plugin.version}</version>
+                <version>1.0.0-beta3</version>
                 <configuration>
-                    <webappDir>src/main/webapp</webappDir>
-                    <discoveryDocDir>${project.build.directory}/generated-sources/appengine-endpoints/WEB-INF</discoveryDocDir>
+                    <!-- plugin configuration -->
                 </configuration>
-                <executions>
-                    <execution>
-                        <phase>generate-sources</phase>
-                        <goals>
-                            <goal>discoveryDocs</goal>
-                        </goals>
-                    </execution>
-                </executions>
             </plugin>
+            <!-- [END endpoints-frameworks-plugin] -->
             <plugin>
                 <groupId>org.codehaus.mojo</groupId>
                 <artifactId>versions-maven-plugin</artifactId>

appengine/endpoints-frameworks-v2/discovery/gradlew renamed to appengine/endpoints-frameworks-v2/migration-example/gradlew

@@ -22,7 +22,6 @@
 public class Constants {
   public static final String WEB_CLIENT_ID = "replace this with your web client ID";
   public static final String ANDROID_CLIENT_ID = "replace this with your Android client ID";
-  public static final String IOS_CLIENT_ID = "replace this with your iOS client ID";
   public static final String ANDROID_AUDIENCE = WEB_CLIENT_ID;
 
   public static final String EMAIL_SCOPE = "https://www.googleapis.com/auth/userinfo.email";

appengine/endpoints-frameworks-v2/discovery/gradlew.bat renamed to appengine/endpoints-frameworks-v2/migration-example/gradlew.bat

@@ -35,7 +35,7 @@
 @Api(name = "helloworld",
     version = "v1",
     scopes = {Constants.EMAIL_SCOPE},
-    clientIds = {Constants.WEB_CLIENT_ID, Constants.ANDROID_CLIENT_ID, Constants.IOS_CLIENT_ID},
+    clientIds = {Constants.WEB_CLIENT_ID, Constants.ANDROID_CLIENT_ID},
     audiences = {Constants.ANDROID_AUDIENCE}
     )
 public class Greetings {

appengine/endpoints-frameworks-v2/discovery/jenkins.sh renamed to appengine/endpoints-frameworks-v2/migration-example/jenkins.sh

@@ -16,7 +16,6 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
     <threadsafe>true</threadsafe>
-    <version>1</version>
     <system-properties>
         <property name="java.util.logging.config.file" value="WEB-INF/logging.properties"/>
     </system-properties>

appengine/endpoints-frameworks-v2/discovery/pom.xml renamed to appengine/endpoints-frameworks-v2/migration-example/pom.xml

@@ -14,17 +14,12 @@ 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.
 -->
+    <!-- Uncomment to use Endpoints Frameworks v1.0 -->
+    <!--
+    [START appengine-endpoints]
     <servlet>
-        <!-- Uncomment to use Endpoints Frameworks v1.0 -->
-        <!--
         <servlet-name>SystemServiceServlet</servlet-name>
         <servlet-class>com.google.api.server.spi.SystemServiceServlet</servlet-class>
-        -->
-        <!-- End of Endpoints Frameworks v1.0 -->
-        <!-- Endpoints Frameworks v2.0 -->
-        <servlet-name>EndpointsServlet</servlet-name>
-        <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
-        <!-- End of Endpoints Frameworks v2.0 -->
         <init-param>
             <param-name>services</param-name>
             <param-value>com.example.helloendpoints.Greetings</param-value>
@@ -35,17 +30,34 @@ limitations under the License.
         </init-param>
     </servlet>
     <servlet-mapping>
-        <!-- Uncomment to use Endpoints Frameworks v1.0 -->
-        <!--
         <servlet-name>SystemServiceServlet</servlet-name>
         <url-pattern>/_ah/spi/*</url-pattern>
-        -->
-        <!-- End of Endpoints Frameworks v1.0 -->
-        <!-- Endpoints Frameworks v2.0 -->
+    </servlet-mapping>
+    [END appengine-endpoints]
+    -->
+    <!-- End of Endpoints Frameworks v1.0 -->
+
+    <!-- Endpoints Frameworks v2.0 -->
+    <!-- [START endpoints-frameworks] -->
+    <servlet>
+        <servlet-name>EndpointsServlet</servlet-name>
+        <servlet-class>com.google.api.server.spi.EndpointsServlet</servlet-class>
+        <init-param>
+            <param-name>services</param-name>
+            <param-value>com.example.helloendpoints.Greetings</param-value>
+        </init-param>
+        <init-param>
+            <param-name>restricted</param-name>
+            <param-value>false</param-value>
+        </init-param>
+    </servlet>
+    <servlet-mapping>
         <servlet-name>EndpointsServlet</servlet-name>
         <url-pattern>/_ah/api/*</url-pattern>
-        <!-- End of Endpoints Frameworks v2.0 -->
     </servlet-mapping>
+    <!-- [END endpoints-frameworks] -->
+    <!-- End of Endpoints Frameworks v2.0 -->
+
     <welcome-file-list>
         <welcome-file>index.html</welcome-file>
     </welcome-file-list>