Merge pull request #1 from apache/dev

Please make sure master-slave data sync on MySQL is running correctly. Otherwise this example will query empty data from slave.

## Using docker-compose to config startup environment

### before we use docker compose, please install docker first : https://docs.docker.com/compose/install/

### usage is as following :

1. access the docker folder (cd docker)

before we use docker compose, please install docker first : https://docs.docker.com/compose/install/

#### sharding-jdbc

1. access the docker folder (cd docker/sharding-jdbc/sharding)

2. launch the environment by docker compose (docker-compose up -d)

3. access mysql / etcd / zookeeper as you want

4. if there is conflict on port, just modify the mapper port in docker-compose.yml and then launch docker compose again(docker-compose up -d)

5. if you want to stop these environment, use command docker-compose stop

5. if you want to stop these environment, use command docker-compose down

#### sharding-proxy

1. access the docker folder (cd docker/sharding-proxy/sharding)

2. launch the environment by docker compose (docker-compose up -d)

3. access proxy by `mysql -h127.0.0.1 -P13308 -proot -uroot`

4. if there is conflict on port, just modify the mapper port in docker-compose.yml and then launch docker compose again(docker-compose up -d)

5. if you want to stop these environment, use command docker-compose down

to clean the docker container , you could use docker rm `docker ps -a -q` (be careful)

## sharding-sphere-example module design

### project module

```

sharding-sphere-example

  ├── example-common

  │   ├── config-utility

  │   ├── repository-api

  │   ├── repository-jdbc

  │   ├── repository-jpa

  │   └── repository-mybatis

  ├── sharding-jdbc-example

  │   ├── orchestration-example

  │   │   ├── orchestration-raw-jdbc-example

  │   │   ├── orchestration-spring-boot-example

  │   │   └── orchestration-spring-namespace-example

  │   ├── sharding-example

  │   │   ├── sharding-raw-jdbc-example

  │   │   ├── sharding-spring-boot-jpa-example

  │   │   ├── sharding-spring-boot-mybatis-example

  │   │   ├── sharding-spring-namespace-jpa-example

  │   │   └── sharding-spring-namespace-mybatis-example

  │   └── transaction-example

  │       ├── transaction-2pc-xa-example

  │       └── transaction-base-saga-example

  ├── sharding-proxy-example

  │   └── sharding-proxy-boot-mybatis-example

  └── src/resources

        └── manual_schema.sql

```

### Best practice for sharding data

* sharding databases

* sharding tables

* sharding databases and tables

* master-slave

* sharding & master-slave

you can get more detail from **[sharding-example](./sharding-jdbc-example/sharding-example)**

### Best practice for sharding + orchestration

* local zookeeper/etcd & sharding

    local sharding configuration can override the configuration of zookeeper/etcd.

* cloud zookeeper/etcd & sharding

    shardingsphere will load the sharding configuration form zookeeper/etcd directly.

you can get more detail from **[orchestration-example](./sharding-jdbc-example/orchestration-example)**

### Best Practice for sharding + distribution-transaction

* 2pc-xa transaction

* base-saga transaction

you can get more detail from **[transaction-example](./sharding-jdbc-example/transaction-example)**

### how to use hint routing

we will add hint example recently.

### how to config none-sharding tables

we will add none-sharding example recently.

### how to config broadcast-table

we will add broadcast-table example recently.

### how to use APM with shardingsphere

we will add APM example recently.

### how to encrypt & decrypt data in shardingsphere

we prefer to add encrypt & decrypt example recently.

### how to use sharding-proxy with jdbc.

we prefer to add a docker base example recently.

/*

 * Licensed to the Apache Software Foundation (ASF) under one or more

 * contributor license agreements.  See the NOTICE file distributed with

 * this work for additional information regarding copyright ownership.

 * The ASF licenses this file to You 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 io.shardingsphere.example.repository.jdbc.repository;

import io.shardingsphere.example.repository.api.entity.OrderItem;

import io.shardingsphere.example.repository.api.repository.OrderItemRepository;

import java.sql.PreparedStatement;

import java.sql.ResultSet;

import java.sql.SQLException;

import java.sql.Statement;

import java.util.LinkedList;

import java.util.List;

public abstract class BaseOrderItemRepository implements OrderItemRepository {

    static final String SQL_INSERT_T_ORDER_ITEM = "INSERT INTO t_order_item (order_id, user_id, status) VALUES (?, ?, ?)";

    static final String SQL_DELETE_BY_ITEM_ID = "DELETE FROM t_order_item WHERE order_item_id=?";

    private static final String SQL_CREATE_T_ORDER_ITEM = "CREATE TABLE IF NOT EXISTS t_order_item "

        + "(order_item_id BIGINT NOT NULL AUTO_INCREMENT, order_id BIGINT NOT NULL, user_id INT NOT NULL, status VARCHAR(50), PRIMARY KEY (order_item_id))";

    private static final String SQL_DROP_T_ORDER_ITEM = "DROP TABLE t_order_item";

    private static final String SQL_TRUNCATE_T_ORDER_ITEM = "TRUNCATE TABLE t_order_item";

    private static final String SQL_SELECT_T_ORDER_ITEM_ALL = "SELECT i.* FROM t_order o, t_order_item i WHERE o.order_id = i.order_id";

    private static final String SQL_SELECT_T_ORDER_ITEM_RANGE = "SELECT i.* FROM t_order o, t_order_item i WHERE o.order_id = i.order_id AND o.user_id BETWEEN 1 AND 5";

    final void createItemTableNotExist(final Statement statement) throws SQLException {

        statement.executeUpdate(SQL_CREATE_T_ORDER_ITEM);

    }

    final void dropItemTable(final Statement statement) throws SQLException {

        statement.executeUpdate(SQL_DROP_T_ORDER_ITEM);

    }

    final void truncateItemTable(final Statement statement) throws SQLException {

        statement.executeUpdate(SQL_TRUNCATE_T_ORDER_ITEM);

    }

    final void insertItem(final PreparedStatement preparedStatement, final OrderItem orderItem) throws SQLException {

        preparedStatement.setLong(1, orderItem.getOrderId());

        preparedStatement.setInt(2, orderItem.getUserId());

        preparedStatement.setString(3, orderItem.getStatus());

        preparedStatement.executeUpdate();

        try (ResultSet resultSet = preparedStatement.getGeneratedKeys()) {

            if (resultSet.next()) {

                orderItem.setOrderItemId(resultSet.getLong(1));

            }

        }

    }

    final void deleteById(final PreparedStatement preparedStatement, final Long orderItemId) throws SQLException {

        preparedStatement.setLong(1, orderItemId);

        preparedStatement.executeUpdate();

    }

    final List<OrderItem> queryOrderItem(final PreparedStatement preparedStatement) {

        List<OrderItem> result = new LinkedList<>();

        try (ResultSet resultSet = preparedStatement.executeQuery()) {

            while (resultSet.next()) {

                OrderItem orderItem = new OrderItem();

                orderItem.setOrderItemId(resultSet.getLong(1));

                orderItem.setOrderId(resultSet.getLong(2));

                orderItem.setUserId(resultSet.getInt(3));

                orderItem.setStatus(resultSet.getString(4));

                result.add(orderItem);

            }

        } catch (final SQLException ignored) {

        }

        return result;

    }

    @Override

    public final List<OrderItem> selectAll() {

        return getOrderItems(SQL_SELECT_T_ORDER_ITEM_ALL);

    }

    @Override

    public final List<OrderItem> selectRange() {

        return getOrderItems(SQL_SELECT_T_ORDER_ITEM_RANGE);

    }

    public abstract List<OrderItem> getOrderItems(String sql);

}

/*

 * Licensed to the Apache Software Foundation (ASF) under one or more

 * contributor license agreements.  See the NOTICE file distributed with

 * this work for additional information regarding copyright ownership.

 * The ASF licenses this file to You 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 io.shardingsphere.example.repository.jdbc.repository;

import io.shardingsphere.example.repository.api.entity.Order;

import io.shardingsphere.example.repository.api.repository.OrderRepository;

import java.sql.PreparedStatement;

import java.sql.ResultSet;

import java.sql.SQLException;

import java.sql.Statement;

import java.util.LinkedList;

import java.util.List;

public abstract class BaseOrderRepository implements OrderRepository {

    static final String SQL_INSERT_T_ORDER = "INSERT INTO t_order (user_id, status) VALUES (?, ?)";

    static final String SQL_DELETE_BY_ORDER_ID = "DELETE FROM t_order WHERE order_id=?";

    private static final String SQL_CREATE_T_ORDER = "CREATE TABLE IF NOT EXISTS t_order (order_id BIGINT NOT NULL AUTO_INCREMENT, user_id INT NOT NULL, status VARCHAR(50), PRIMARY KEY (order_id))";

    private static final String SQL_DROP_T_ORDER = "DROP TABLE t_order";

    private static final String SQL_TRUNCATE_T_ORDER = "TRUNCATE TABLE t_order";

    private static final String SQL_SELECT_T_ORDER_ALL = "SELECT * FROM t_order";

    private static final String SQL_SELECT_T_ORDER_RANGE = "SELECT * FROM t_order WHERE order_id BETWEEN 200000000000000000 AND 400000000000000000";

    final void createOrderTableNotExist(final Statement statement) throws SQLException {

        statement.executeUpdate(SQL_CREATE_T_ORDER);

    }

    final void dropOrderTable(final Statement statement) throws SQLException {

        statement.executeUpdate(SQL_DROP_T_ORDER);

    }

    final void truncateOrderTable(final Statement statement) throws SQLException {

        statement.executeUpdate(SQL_TRUNCATE_T_ORDER);

    }

    final void insertOrder(final PreparedStatement preparedStatement, final Order order) throws SQLException {

        preparedStatement.setInt(1, order.getUserId());

        preparedStatement.setString(2, order.getStatus());

        preparedStatement.executeUpdate();

        try (ResultSet resultSet = preparedStatement.getGeneratedKeys()) {

            if (resultSet.next()) {

                order.setOrderId(resultSet.getLong(1));

            }

        }

    }

    final void deleteById(final PreparedStatement preparedStatement, final Long orderId) throws SQLException {

        preparedStatement.setLong(1, orderId);

        preparedStatement.executeUpdate();

    }

    final List<Order> queryOrder(final PreparedStatement preparedStatement) {

        List<Order> result = new LinkedList<>();

        try (ResultSet resultSet = preparedStatement.executeQuery()) {

            while (resultSet.next()) {

                Order order = new Order();

                order.setOrderId(resultSet.getLong(1));

                order.setUserId(resultSet.getInt(2));

                order.setStatus(resultSet.getString(3));

                result.add(order);

            }

        } catch (final SQLException ignored) {

        }

        return result;

    }

    @Override

    public final List<Order> selectAll() {

        return getOrders(SQL_SELECT_T_ORDER_ALL);

    }

    @Override

    public final List<Order> selectRange() {

        return getOrders(SQL_SELECT_T_ORDER_RANGE);

    }

    public abstract List<Order> getOrders(String sql);

}

/*

 * Copyright 2016-2018 shardingsphere.io.

 * <p>

 * 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.

 * </p>

 */

package io.shardingsphere.example.repository.jdbc.repository;

import io.shardingsphere.example.repository.api.entity.OrderItem;

import io.shardingsphere.example.repository.api.repository.OrderItemRepository;

import java.sql.Connection;

import java.sql.PreparedStatement;

import java.sql.SQLException;

import java.sql.Statement;

import java.util.LinkedList;

import java.util.List;

public final class JDBCOrderItemTransactionRepositoryImpl extends BaseOrderItemRepository implements OrderItemRepository {

    private Connection connection;

    public JDBCOrderItemTransactionRepositoryImpl(final Connection connection) {

        this.connection = connection;

    }

    public void setConnection(final Connection connection) {

        this.connection = connection;

    }

    @Override

    public void createTableIfNotExists() {

        try (Statement statement = connection.createStatement()) {

            createItemTableNotExist(statement);

        } catch (final SQLException ignored) {

        }

    }

    @Override

    public void dropTable() {

        try (Statement statement = connection.createStatement()) {

            dropItemTable(statement);

        } catch (final SQLException ignored) {

        }

    }

    @Override

    public void truncateTable() {

        try (Statement statement = connection.createStatement()) {

            truncateItemTable(statement);

        } catch (final SQLException ignored) {

        }

    }

    @Override

    public Long insert(final OrderItem orderItem) {

        try (PreparedStatement preparedStatement = connection.prepareStatement(SQL_INSERT_T_ORDER_ITEM, Statement.RETURN_GENERATED_KEYS)) {

            insertItem(preparedStatement, orderItem);

        } catch (final SQLException ignored) {

        }

        return orderItem.getOrderItemId();

    }

    @Override

    public void delete(final Long orderItemId) {

        try (PreparedStatement preparedStatement = connection.prepareStatement(SQL_DELETE_BY_ITEM_ID)) {

            deleteById(preparedStatement, orderItemId);

        } catch (final SQLException ignored) {

        }

    }

    @Override

    public List<OrderItem> getOrderItems(final String sql) {

        List<OrderItem> result = new LinkedList<>();

        try (PreparedStatement preparedStatement = connection.prepareStatement(sql)) {

            result = queryOrderItem(preparedStatement);

        } catch (final SQLException ignored) {

        }

        return result;

    }

}

/*

 * Copyright 2016-2018 shardingsphere.io.

 * <p>

 * 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.

 * </p>

 */

package io.shardingsphere.example.repository.jdbc.repository;

import io.shardingsphere.example.repository.api.entity.Order;

import io.shardingsphere.example.repository.api.repository.OrderRepository;

import java.sql.Connection;

import java.sql.PreparedStatement;

import java.sql.SQLException;

import java.sql.Statement;

import java.util.LinkedList;

import java.util.List;

public final class JDBCOrderTransactionRepositoryImpl extends BaseOrderRepository implements OrderRepository {

    private Connection connection;

    public JDBCOrderTransactionRepositoryImpl(final Connection connection) {

        this.connection = connection;

    }

    public void setConnection(final Connection connection) {

        this.connection = connection;

    }

    @Override

    public void createTableIfNotExists() {

        try (Statement statement = connection.createStatement()) {

            createOrderTableNotExist(statement);

        } catch (final SQLException ignored) {

        }

    }

    @Override

    public void dropTable() {

        try (Statement statement = connection.createStatement()) {

            dropOrderTable(statement);

        } catch (final SQLException ignored) {

        }

    }

    @Override

    public void truncateTable() {

        try (Statement statement = connection.createStatement()) {

            truncateOrderTable(statement);

        } catch (final SQLException ignored) {

        }

    }

    @Override

    public Long insert(final Order order) {

        try (PreparedStatement preparedStatement = connection.prepareStatement(SQL_INSERT_T_ORDER, Statement.RETURN_GENERATED_KEYS)) {

            insertOrder(preparedStatement, order);

        } catch (final SQLException ignored) {

        }

        return order.getOrderId();

    }

    @Override

    public void delete(final Long id) {

        try (PreparedStatement preparedStatement = connection.prepareStatement(SQL_DELETE_BY_ORDER_ID)) {

            deleteById(preparedStatement, id);

        } catch (final SQLException ignored) {

        }

    }

    @Override

    public List<Order> getOrders(final String sql) {

        List<Order> result = new LinkedList<>();

        try (PreparedStatement preparedStatement = connection.prepareStatement(sql)) {

            result = queryOrder(preparedStatement);

        } catch (final SQLException ignored) {

        }

        return result;

    }

}