API Multiclass

Jika satu API sangat kompleks, Anda mungkin ingin mengimplementasikannya dari beberapa class Java. Untuk membuat class yang berbeda menjadi bagian dari API yang sama, Anda harus:

Beri setiap class string name dan version yang sama dalam anotasi @Api-nya.
Menambahkan API class sebagai daftar yang dipisahkan koma di web.xml.

Misalnya, dua class berikut adalah bagian dari tictactoe API:

@Api(name = "tictactoe", version = "v1")
class TicTacToeA { … }

@Api(name = "tictactoe", version = "v1")
class TicTacToeB { … }

Konfigurasi API ditetapkan melalui properti anotasi @Api. Namun, untuk beberapa class di API yang sama, persyaratan @Api tidak hanya memiliki string name dan version yang sama dalam anotasi @Api untuk setiap class. Bahkan, API backend Anda tidak akan berfungsi jika ada perbedaan dalam konfigurasi API yang ditetapkan dalam properti @Api class. Setiap perbedaan dalam properti @Api untuk class di API multiclass akan menghasilkan konfigurasi API yang " ambigu", yang tidak akan berfungsi di Framework Cloud Endpoints untuk App Engine.

Ada beberapa cara untuk membuat API multiclass yang jelas:

Pastikan secara manual semua class dalam satu API memiliki properti anotasi @Api yang sama persis.
Menggunakan pewarisan anotasi melalui pewarisan Java. Dalam pewarisan ini, semua class dalam satu API mewarisi konfigurasi API yang sama dari class dasar beranotasi @Api umum.
Gunakan pewarisan anotasi melalui anotasi @ApiReference pada semua class dalam satu API agar mereferensikan konfigurasi API yang sama dari class umum beranotasi @Api.

Menggunakan `@ApiClass` untuk properti yang dapat berbeda di antara class

Untuk menggunakan fitur ini, Anda memerlukan impor berikut:

import com.google.api.server.spi.config.ApiClass;

Meskipun semua properti dalam anotasi @Api harus cocok untuk semua class dalam API, Anda juga dapat menggunakan anotasi @ApiClass untuk menyediakan properti yang tidak harus sama persis di antara class. Contoh:

// API methods implemented in this class allow only "clientIdA".
@Api(name = "tictactoe", version = "v1")
@ApiClass(clientIds = { "clientIdA" })
class TicTacToeA { … }

// API methods implemented in this class provide unauthenticated access.
@Api(name = "tictactoe", version = "v1")
class TicTacToeB { … }

dengan TicTacToeA membatasi akses menggunakan daftar client ID yang diizinkan yang berisi client ID yang diizinkan, dan TicTacToeB tidak membatasi akses.

Semua properti yang diberikan oleh anotasi @ApiClass memiliki properti yang setara dalam anotasi @Api. Perhatikan bahwa properti yang setara dengan @Api berfungsi sebagai default seluruh API. Jika ada default seluruh API untuk properti yang sama, yang ditentukan dalam @Api, properti @ApiClass khusus class akan menggantikan default seluruh API.

Contoh berikut menggambarkan penggantian properti @Api oleh @ApiClass khusus class yang setara:

// For this class "boards" overrides "games".
@Api(name = "tictactoe", version = "v1", resource = "games")
@ApiClass(resource = "boards")
class TicTacToeBoards { … }

// For this class "scores" overrides "games".
@Api(name = "tictactoe", version = "v1", resource = "games")
@ApiClass(resource = "scores")
class TicTacToeScores { … }

// For this class, the API-wide default "games" is used as the resource.
@Api(name = "tictactoe", version = "v1", resource = "games")
class TicTacToeGames { … }

Pewarisan anotasi

Properti anotasi @Api dan @ApiClass dapat diwarisi dari class lain, dan masing-masing properti dapat diganti melalui pewarisan Java atau pewarisan @ApiReference

Menggunakan pewarisan Java

Class yang memperluas class lain dengan anotasi @Api atau @ApiClass berperilaku seolah-olah dianotasi dengan properti yang sama. Contoh:

@Api(name = "tictactoe", version = "v1")
class TicTacToeBase { … }

// TicTacToeA and TicTacToeB both behave as if they have the same @Api annotation as
// TicTacToeBase
class TicTacToeA extends TicTacToeBase { … }
class TicTacToeB extends TicTacToeBase { … }

Anotasi hanya diwariskan melalui subclass Java, bukan melalui implementasi antarmuka. Contoh:

@Api(name = "tictactoe", version = "v1")
interface TicTacToeBase { … }
// Does *not* behave as if annotated.
class TicTacToeA implements TicTacToeBase { … }

Oleh karena itu, tidak ada dukungan untuk beberapa pewarisan anotasi framework.

Pewarisan juga berfungsi untuk @ApiClass:

@ApiClass(resource = "boards")
class BoardsBase { … }

// TicTacToeBoards behaves as if annotated with the @ApiClass from BoardsBase.
// Thus, the "resource" property will be "boards".
@Api(name = "tictactoe", version = "v1", resource = "scores")
class TicTacToeBoards extends BoardsBase { … }

tempat TicTacToeBoards mewarisi nilai properti resource boards dari BoardsBase, sehingga mengganti setelan properti resource (scores) dalam anotasi @Api-nya. Perlu diingat bahwa jika ada class yang telah menentukan properti resource dalam anotasi @Api, semua class harus menentukan setelan yang sama dalam anotasi @Api; teknik pewarisan ini memungkinkan Anda mengganti properti @Api tersebut.

Menggunakan pewarisan `@ApiReference`

Untuk menggunakan fitur ini, Anda memerlukan impor berikut:

import com.google.api.server.spi.config.ApiReference;

Anotasi @ApiReference menyediakan cara alternatif untuk menentukan pewarisan anotasi. Class yang menggunakan @ApiReference untuk menentukan class lain dengan anotasi @Api atau @ApiClass akan berperilaku seolah-olah dianotasi dengan properti yang sama. Contoh:

@Api(name = "tictactoe", version = "v1")
class TicTacToeBase { … }

// TicTacToeA behaves as if it has the same @Api annotation as TicTacToeBase
@ApiReference(TicTacToeBase.class)
class TicTacToeA { … }

Jika pewarisan Java dan @ApiReference digunakan, anotasi hanya akan mewarisi melalui anotasi @ApiReference. Anotasi @Api dan @ApiClass pada class yang diwarisi melalui pewarisan Java akan diabaikan. Misalnya:

@Api(name = "tictactoe", version = "v1")
class TicTacToeBaseA { … }
@Api(name = "tictactoe", version = "v2")
class TicTacToeBaseB { … }

// TicTacToe will behave as if annotated the same as TicTacToeBaseA, not TicTacToeBaseB.
// The value of the "version" property will be "v1".
@ApiReference(TicTacToeBaseA.class)
class TicTacToe extends TicTacToeBaseB { … }

Mengganti konfigurasi yang diwariskan

Baik mewarisi konfigurasi menggunakan pewarisan Java atau @ApiReference, Anda dapat mengganti konfigurasi yang diwarisi menggunakan anotasi @Api atau @ApiClass baru. Hanya properti konfigurasi yang ditentukan dalam anotasi baru yang diganti. Properti yang tidak ditentukan masih diwariskan. Contoh:

@Api(name = "tictactoe", version = "v2")
class TicTacToe { … }

// Checkers will behave as if annotated with name = "checkers" and version = "v2"
@Api(name = "checkers")
class Checkers extends TicTacToe { … }

Mengganti pewarisan juga berfungsi untuk @ApiClass:

@Api(name = "tictactoe", version = "v1")
@ApiClass(resource = "boards", clientIds = { "c1" })
class Boards { … }

// Scores will behave as if annotated with resource = "scores" and clientIds = { "c1" }
@ApiClass(resource = "scores")
class Scores { … }

Mengganti juga berfungsi saat mewarisi melalui @ApiReference:

@Api(name = "tictactoe", version = "v2")
class TicTacToe { … }

// Checkers will behave as if annotated with name = "checkers" and version = "v2"
@ApiReference(TicTacToe.class)
@Api(name = "checkers")
class Checkers { … }

Mewarisi anotasi `@ApiMethod`

Anotasi @ApiMethod dapat diwarisi dari metode yang diganti. Misalnya:

class TicTacToeBase {
  @ApiMethod(httpMethod = "POST")
  public Game setGame(Game game) { … }
}
@Api(name = "tictactoe", version = "v1")
class TicTacToe extends TicTacToeBase {
  // setGame behaves as if annotated with the @ApiMethod from TicTacToeBase.setGame.
  // Thus the "httpMethod" property will be "POST".
  @Override
  public Game setGame(Game game) { … }
}

Demikian pula dengan pewarisan anotasi @Api dan @ApiClass, jika beberapa metode yang mengganti satu sama lain memiliki anotasi @ApiMethod, masing-masing properti dapat diganti. Contoh:

class TicTacToeBase {
  @ApiMethod(httpMethod = "POST", clientIds = { "c1" })
  public Game setGame(Game game) { … }
}
@Api(name = "tictactoe", version = "v1")
class TicTacToe extends TicTacToeBase {
  // setGame behaves as if annotated with httpMethod = "GET" and clientIds = { "c1"}.
  @ApiMethod(httpMethod = "GET")
  @Override
  public Game setGame(Game game) { … }
}

Tidak ada anotasi @ApiReference atau yang setara untuk metode, sehingga @ApiMethod selalu diwarisi melalui pewarisan Java, bukan melalui @ApiReference.

Aturan turunan dan preseden

Untuk menyintesis diskusi sebelumnya, tabel berikut menunjukkan aturan pewarisan dan urutan prioritas.

Anotasi/pewarisan	Aturan
`@Api`	Harus sama untuk semua kelas.
`@ApiClass`	Ditentukan untuk class guna mengganti properti `@Api`.
Pewarisan Java	Class mewarisi `@Api` dan `@ApiClass` class dasar.
`@ApiReference`	Class mewarisi `@Api` dan `@ApiClass` dari class yang direferensikan.
Menggunakan `@ApiReference` pada class (Java) yang mewarisi dari class dasar	Class mewarisi `@Api` dan `@ApiClass` dari class yang direferensikan, bukan dari class dasar.

Kasus penggunaan umum untuk pewarisan anotasi

Berikut adalah contoh kasus penggunaan umum untuk pewarisan:

Untuk pembuatan versi API:

@Api(name = "tictactoe", version = "v1")
class TicTacToeV1 { … }
@Api(version = "v2")
class TicTacToeV2 extends TicTacToeV1 { … }

Untuk API multiclass:

@Api(name = "tictactoe", version = "v1")
class TicTacToeBase {}
@ApiClass(resource = "boards")
class TicTacToeBoards extends TicTacToeBase { … }
@ApiClass(resource = "scores")
class TicTacToeScores extends TicTacToeBase { … }

Untuk menguji versi lain dari API yang sama:

@Api(name = "tictactoe", version = "v1")
class TicTacToe {
  protected Foo someMethod() {
    // Do something real;
  }

  public Foo getFoo() { … }
}

@Api(version="v1test")
class TicTacToeTest extends TicTacToe {
  protected Foo someMethod() {
    // Stub out real action;
  }
}

saat someMethod dapat menampilkan respons yang telah ditentukan sebelumnya, menghindari panggilan dengan efek samping, melewati permintaan jaringan atau datastore, dan sebagainya.

Menambahkan class ke `web.xml`

Setelah memberikan anotasi ke kelas, Anda harus menambahkannya ke file web.xml. Contoh berikut menunjukkan satu class:

<web-app xmlns="http://xmlns.jcp.org/xml/ns/javaee"
         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
         xsi:schemaLocation="http://xmlns.jcp.org/xml/ns/javaee
         http://xmlns.jcp.org/xml/ns/javaee/web-app_3_1.xsd"
         version="3.1">
    <!-- Wrap the backend with Endpoints Frameworks v2. -->
    <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.skeleton.MyApi</param-value>
        </init-param>
    </servlet>
    <!-- Route API method requests to the backend. -->
    <servlet-mapping>
        <servlet-name>EndpointsServlet</servlet-name>
        <url-pattern>/_ah/api/*</url-pattern>
    </servlet-mapping>
</web-app>

Untuk menambahkan beberapa kelas:

Ganti <param-value>com.example.skeleton.MyApi</param-value> dengan nama class API Anda sendiri.

Tambahkan setiap class dalam kolom <param-value> yang sama ini yang dipisahkan dengan koma, misalnya:

<param-value>com.example-company.example-api.Hello,com.example-company.example-api.Goodbye</param-value>