Coder Social home page Coder Social logo

yahoo / parsec Goto Github PK

View Code? Open in Web Editor NEW
34.0 14.0 20.0 105.98 MB

A collection of libraries and utilities to simplify the process of building web service applications.

License: Apache License 2.0

Shell 2.56% Groovy 29.08% Java 68.36%
build-tools parsec web-services rdl gradle jersey2 web mobile

parsec's Introduction

Parsec Build Status

Parsec is a collection of libraries and utilities built upon Gradle and Jersey2, with the reliance on RDL. It is designed to reduce the effort of building web service applications, allowing you to spend more quality time elsewhere. By using Parsec, the grunt work is handled so you can concentrate on the logic and implementation side of development. More importantly, Parsec also provides flexibility and abstraction such that you can easily enforce your own standard, and apply to the pipeline.

Parsec offers a standardized end-to-end solution to quickly bring web service applications from concept to production. The goal of Parsec is to:

  • Provide a standard method for building APIs
  • Eliminate time spent in project and environment set up
  • Minimize time and effort spent on common repetitive tasks
  • Provide helper libraries and utilities for common tasks
  • Reduce the learning curve and maintenance cost
  • Provide client for your web service

If you are building a new project with Java, Parsec is definitely a good starting point.

Getting Started

Requirements

  • Java 1.8: check your jdk version using $ java -version or download Java JDK 1.8
  • Gradle (recommended version: >2.4): check your gradle version using $ gradle --v or run

$ sudo brew install gradle to install the latest gradle

After having Java 1.8 and Gradle installed with the proper version, you must do a one time setup to allow you to create a Parsec project without a build.gradle script.

$ vim ~/.gradle/init.gradle , then enter the following code:

gradle.beforeProject { prj ->
   prj.apply from: 'https://raw.githubusercontent.com/yahoo/parsec/master/parsec-template-plugin/installation/apply.groovy'
}

Create a New Project

To create a new Parsec project, run:

$ gradle createParsecProject -PgroupId='your.group.name' -PartifactId='your_project_name'

groupId refers to the namespace of your package, while the artifactId is your project name. If you do not specify the groupId or artifactId, you will be prompted to do so.

Create Schema

You need one or more RDL schema files to define your API specifications; they should be placed under src/main/rdl/ and be named as *.rdl. RDL is a machine-readable description of a schema that describes data types, as well as resources using those types.

You can start with this sample RDL file, save it as src/main/rdl/sample.rdl:

namespace your.group.name;
name sample;
version 1;

type User struct {
    string name (x_not_null="groups=insert", x_size="min=3,max=5,groups=update|insert");
    string occupation (x_not_null="groups=update", x_size="min=4,groups=update|insert");
    int32 age;
    string id (x_null="groups=insert");
}

resource User GET "/users/{id}" {
    int32 id;

    expected OK;
    exceptions {
        ResourceError INTERNAL_SERVER_ERROR;
        ResourceError BAD_REQUEST;
        ResourceError UNAUTHORIZED;
        ResourceError FORBIDDEN;
    }
}

resource string POST "/users" {
    User user (x_must_validate="insert");

    expected OK;
    exceptions {
        ResourceError INTERNAL_SERVER_ERROR;
        ResourceError BAD_REQUEST;
        ResourceError UNAUTHORIZED;
        ResourceError FORBIDDEN;
    }
}

resource string PUT "/users/{id}" {
    int32 id ;

    User user (x_must_validate="update");

    expected OK;
    exceptions {
        ResourceError INTERNAL_SERVER_ERROR;
        ResourceError BAD_REQUEST;
        ResourceError UNAUTHORIZED;
        ResourceError FORBIDDEN;
    }

}

Generate Code

After you have added your rdl files in the folder, you can use the command below to generate files:

$ gradle parsec-generate

Here is an example of the generated folder structure, based on the sample.rdl above:

$ tree build/generated-sources/
build/generated-sources/
└── java
    └── your
        └──group
            └──name
                └──parsec_generated
                    ├── ParsecApplication.java
                    ├── ParsecErrorBody.java
                    ├── ParsecErrorDetail.java
                    ├── ParsecExceptionMapper.java
                    ├── ParsecResourceError.java
                    ├── ParsecValidationGroups.java
                    ├── ParsecWebListener.java
                    ├── ParsecWrapperServlet.java
                    ├── ResourceContext.java
                    ├── ResourceError.java
                    ├── ResourceException.java
                    ├── SampleHandler.java
                    ├── SampleResources.java
                    ├── SampleServer.java
                    └── User.java

4 directories, 15 files

$ tree src/main/java/
src/main/java/
└── your
    └── group
        └──name
            ├── DefaultApplication.java
            ├── DefaultExceptionMapper.java
            ├── DefaultResourceContext.java
            ├── DefaultWebListener.java
            ├── SampleClient.java
            ├── SampleClientImpl.java
            └── SampleHandlerImpl.java

2 directories, 7 files

Parsec generated Java server, model code, and Java client for the server. The generated code would include:

  • Java models / data objects, for example: User.java
  • Jersey resource endpoints, for example: SampleResource.java
  • Handler interfaces, for example: SampleHandler.java - Handler implementations follow a naming convention: HandlerImpl.java
  • Java client for your web service, for example: SampleClient.java, SampleClientImpl.java

Java files are generated under ${baseDir}/build/generated-sources/java and the generated Java code are in sub-package .parsec_generated

Implement Handlers

Now you can start to implement your API by editing *HandlerImpl.java files. Here is an example of SampleHandlerImpl.java:

package your.group.name;

import your.group.name.parsec_generated.User;
import your.group.name.parsec_generated.SampleHandler;
import your.group.name.parsec_generated.ResourceContext;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

/**
 * SampleHandlerImpl is interface implementation that implement SampleHandler interface.
 */
public class SampleHandlerImpl implements SampleHandler {

    @Override
    public User getUsersById(ResourceContext context, Integer id) {
        User user = new User();
        user.setName("user");
        return user;
    }

    @Override
    public String postUsers(ResourceContext context, User user) {
        return "Post to user " + user.getName() + "!\n";
    }

    @Override
    public String putUsersById(ResourceContext context, Integer id, User user) {
        return "put to user " + user.getName() + " by id " + id + "!\n";
    }

    @Override
    public ResourceContext newResourceContext(HttpServletRequest request, HttpServletResponse response) {
        return new DefaultResourceContext(request, response);
    }
}

Start your Server

Now you can start your server with:

$ gradle jettyRun

Check out your Swagger dashboard

Now you can run test with:

$ curl http://localhost:8080/api/sample/v1/users/1

{"age":0,"name":"user"}

$ curl -H 'Content-Type: application/json' -d '{"name":"user","age":10}' http://localhost:8080/api/sample/v1/users

Welcome to Parsec, user!

Use generated java client

Parsec friendly generates a simple client for your web service, including the interface and the implementation. Client implementation is base on com.ning.http.client.AsyncHttpClient, you can directly use it or modify it by your needs.

Here is the example of SampleClient.java, which provides methods to the APIs defined in src/main/rdl/sample.rdl.

package your.group.name;

import java.util.concurrent.CompletableFuture;
import your.group.name.parsec_generated.ResourceException;
import your.group.name.parsec_generated.User;


public interface SampleClient {
    CompletableFuture<User> getUser(int id) throws ResourceException;
    CompletableFuture<String> postUser(User user) throws ResourceException;
    CompletableFuture<String> putUser(int id, User user) throws ResourceException;
}

License

Copyright 2016, Yahoo Inc. Copyrights licensed under the Apache 2.0 License. See the accompanying LICENSE file for terms.

parsec's People

Contributors

andyyeh avatar ben-tsai avatar chinkong83 avatar geekybaiyi avatar joejoe321321 avatar pchiang-yahoo avatar shichung avatar whatup1981 avatar yamlin avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

parsec's Issues

"Getting Started" no longer works

The file referenced in the README "Getting Started" section (https://raw.githubusercontent.com/yahoo/parsec/master/parsec-template-plugin/installation/apply.groovy) no longer exists. Can you please update it with the correct link?

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.