Skip to content

Commit

Permalink
fixed some grammar/readability
Browse files Browse the repository at this point in the history
  • Loading branch information
Andrew Perlitch committed Jan 26, 2017
1 parent e4d4f0f commit b685531
Show file tree
Hide file tree
Showing 2 changed files with 37 additions and 39 deletions.
54 changes: 27 additions & 27 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,14 +7,14 @@ Continuous Integration [![Build Status](https://travis-ci.org/raphaeljolivet/jav

**Java2Typescript** provides a bridge between a **Java** REST service definition and a **Typescript** client.

It enables to expose the full DTO model and REST services API as a clean typescript definition file, thus enabling strong type checking on the model of your application.
It enables you to expose a full DTO model and REST services API as a clean typescript definition file, thus enabling strong type-checking on the models of your application.

This project is composed of 3 modules :
* **[java2typescript-jackson](java2typescript-jackson)**: A [Jackson](http://jackson.codehaus.org/) module that generate **typescript** definition files for Java classes, using a Jackson ObjectMapper.
* **[java2typescript-jackson](java2typescript-jackson)**: A [Jackson](http://jackson.codehaus.org/) module that generates **typescript** definition files for Java classes, using a Jackson ObjectMapper.
* **[java2typescript-jaxrs](java2typescript-jaxrs)**: An extension to **java2typescript-jackson** that takes a [JAX-RS](https://jax-rs-spec.java.net/) annotated java class and produces both :
* A Typescript definition file of the service (`.d.ts`), together with description of all needed DTO objects.
* An implementation `.js `of the above definition as REST client stub.
* **[java2typescript-maven-plugin](java2typescript-maven-plugin)**: A maven plugin to automate the generation of `.d.ts` and `.js` implementation of REST services.
* An `.js` implementation of the above definition as a REST client stub.
* **[java2typescript-maven-plugin](java2typescript-maven-plugin)**: A maven plugin to automate the generation of a `.d.ts` file and a `.js` implementation of REST services.
* A **[sample web application](sample-web-app)** that demonstrate the usage of **java2typescript**

## Big picture
Expand Down Expand Up @@ -45,20 +45,20 @@ Consider the following JAX-RS service
```java
@Path( "/people" )
public interface PeopleRestService {
@Produces( { MediaType.APPLICATION_JSON } )
@GET
public Collection< Person > getPeoples( @QueryParam( "page") @DefaultValue( "1" ) final int page ) {
return peopleService.getPeople( page, 5 );
}

@Produces( { MediaType.APPLICATION_JSON } )
@Path( "/{email}" )
@GET
public Person getPeople( @PathParam( "email" ) final String email ) {
return peopleService.getByEmail( email );
}
@Produces( { MediaType.APPLICATION_JSON } )
@GET
public Collection< Person > getPeoples( @QueryParam( "page") @DefaultValue( "1" ) final int page ) {
return peopleService.getPeople( page, 5 );
}

@Produces( { MediaType.APPLICATION_JSON } )
@Path( "/{email}" )
@GET
public Person getPeople( @PathParam( "email" ) final String email ) {
return peopleService.getByEmail( email );
}
}
```

Expand All @@ -84,12 +84,12 @@ export var adapter: (httpMethod: string, path: string, getParams: Object, postPa
}
```

The module **People** contains both the definition of the DTO **Person** and the service **PeopleRestService**, it also provides 3 properties :
The module **People** contains both the definitions of the DTO **Person** and the service **PeopleRestService**. It also provides 3 properties :
* **rootURL** : URL of the service : Should be set before usage
* **peopleRESTService** : An instance of the service
* **adapter** : An adapter for RESt service call. Set to Jquery adapter by default.
* **adapter** : An adapter for REST service call. Set to Jquery adapter by default.

Then, in your application, you can call the service like so
Then, in your application, you can call the service like so:
```typescript
/// <reference path="People.d.ts" />
import p = People;
Expand All @@ -108,15 +108,15 @@ Don't forget to import the generated file **People.js** in the final HTML page.

### Installation

To install the library using Maven add [JitPack](https://jitpack.io/) repository and java2typescript dependency:
To install the library using Maven, add the [JitPack](https://jitpack.io/) repository and java2typescript dependency:

```xml
...
<repositories>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
<repository>
<id>jitpack.io</id>
<url>https://jitpack.io</url>
</repository>
</repositories>
...
<dependencies>
Expand All @@ -129,7 +129,7 @@ To install the library using Maven add [JitPack](https://jitpack.io/) repository
...
```

> Note, artifacts for this project are built automatically by [JitPack](https://jitpack.io/docs/#how-to) based on github repository.
> Note, artifacts for this project are built automatically by [JitPack](https://jitpack.io/docs/#how-to) based on the github repository.
> Note, if You are only interested in generating TypeScript definitions from Java classes, You can use `java2typescript-jackson` instead of `java2typescript-maven-plugin` as the artifact id.
Expand Down
22 changes: 10 additions & 12 deletions java2typescript-jackson/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,7 @@ Java classes are converted to TypeScript interfaces.


### Module (generated output) format
TypeScript has concept of [internal](http://www.typescriptlang.org/Handbook#modules) and [external](http://www.typescriptlang.org/Handbook#modules-going-external) modules, that have slightly different format (see the test output for [internal](src/test/resources/java2typescript/jackson/module/DefinitionGeneratorTest.internalModuleFormat.d.ts) vs [external](src/test/resources/java2typescript/jackson/module/DefinitionGeneratorTest.externalModuleFormat.d.ts) module format). By default internal module format is used (that adds one line before and after content of external module format).

External module format can be used by using different ModuleWriter (ExternalModuleFormatWriter - see [the test for an example](src/test/java/java2typescript/jackson/module/DefinitionGeneratorTest.java#L85-L97))
TypeScript has a concept of [internal](http://www.typescriptlang.org/Handbook#modules) and [external](http://www.typescriptlang.org/Handbook#modules-going-external) modules, that have slightly different formats (see the test output for [internal](src/test/resources/java2typescript/jackson/module/DefinitionGeneratorTest.internalModuleFormat.d.ts) vs [external](src/test/resources/java2typescript/jackson/module/DefinitionGeneratorTest.externalModuleFormat.d.ts) module format). By default, internal module format is used (that adds one line before and after content of external module format). To write in the external module format, use the `ExternalModuleFormatWriter` class (see [the test for an example](src/test/java/java2typescript/jackson/module/DefinitionGeneratorTest.java#L85-L97)).


### Ignored methods
Expand All @@ -24,32 +22,32 @@ When generating TypeScript from Java classes <sup>(actually when Java classes ar

See the [tests for excluded methods](src/test/java/java2typescript/jackson/module/ExcludedMethodsTest.java#L33-L65) for details.

> Note: You can also extend the configuration and overwrite [`isIgnoredMethod`](src/main/java/java2typescript/jackson/module/Configuration.java#L44-L49) method to programmatically make the decision (most likely based on method signature: parameters, return type, declaring class, annotations, ...)
> Note: You can also extend the configuration and overwrite the [`isIgnoredMethod`](src/main/java/java2typescript/jackson/module/Configuration.java#L44-L49) method to programmatically make the decision (most likely based on method signature: parameters, return type, declaring class, annotations, ...). You may also want to override this method to always return true if you don't want to include any methods in your Typescript definitions.

### Enums
Java enums are converted to TypeScript enums by default,
but TypeSafe enum pattern can be used to force generating classes instead of enums (see [the description of the issue](https://github.com/raphaeljolivet/java2typescript/issues/13).
Example [output](src/test/resources/java2typescript/jackson/module/WriterPreferencesTest.enumToEnumPattern.d.ts) from test that [turns on this preference](src/test/java/java2typescript/jackson/module/WriterPreferencesTest.java#L44) using
but TypeSafe enum pattern can be used to force the generation of classes instead of enums (see [the description of the issue](https://github.com/raphaeljolivet/java2typescript/issues/13).
See [this output](src/test/resources/java2typescript/jackson/module/WriterPreferencesTest.enumToEnumPattern.d.ts) from the [test that turns on this preference](src/test/java/java2typescript/jackson/module/WriterPreferencesTest.java#L44) using

```Java
mWriter.preferences.useEnumPattern();
```

### Mapping specific java classes to custom TypeScript types
There are scenarios when You might want to use different TypeScript type instead of specific Java Type. There are several options for doing this depending how You want it to be done:
There are scenarios when you might want to use a different TypeScript type instead of the default Java Type. There are several options for doing this depending how you want it to be done:

##### Renaming Type and emitting it to the output
Logic, that determines the name of TypeScript type based on Java class is implemented using [TSTypeNamingStrategy](src/main/java/java2typescript/jackson/module/conf/typename/TSTypeNamingStrategy.java) interface. Currently there are two implementations provided out of the box by this library:
1. [SimpleJacksonTSTypeNamingStrategy](src/main/java/java2typescript/jackson/module/conf/typename/SimpleJacksonTSTypeNamingStrategy.java) - The default, uses Java class name for TypeScript type, unless class has annotation, that specifies custom name (see bellow).
1. [WithEnclosingClassTSTypeNamingStrategy](jackson/module/conf/typename/WithEnclosingClassTSTypeNamingStrategy.java) - extends SimpleJacksonTSTypeNamingStrategy to include enclosing class name as a prefix (`javaClass.getName()` without package ).
Logic that determines the TypeScript type based on Java class is implemented using the [TSTypeNamingStrategy](src/main/java/java2typescript/jackson/module/conf/typename/TSTypeNamingStrategy.java) interface. Currently there are two implementations provided out of the box by this library:
1. [SimpleJacksonTSTypeNamingStrategy](src/main/java/java2typescript/jackson/module/conf/typename/SimpleJacksonTSTypeNamingStrategy.java) - The default, uses the Java class name for the TypeScript type, unless the class has an annotation that specifies a custom name (see bellow).
1. [WithEnclosingClassTSTypeNamingStrategy](jackson/module/conf/typename/WithEnclosingClassTSTypeNamingStrategy.java) - extends SimpleJacksonTSTypeNamingStrategy to include the enclosing class name as a prefix (`javaClass.getName()` without package).

###### Renaming Type using annotation on the Java class (SimpleJacksonTSTypeNamingStrategy)
You can use `@com.fasterxml.jackson.annotation.JsonTypeName("ChangedEnumName")` annotation on the Java type to use different name in TypeScript output (interface/enum with different name is also generated to the output).
You can use the `@com.fasterxml.jackson.annotation.JsonTypeName("ChangedEnumName")` annotation on the Java type to use a different name in TypeScript output (interface/enum with different name is also generated in the output).
See the [example from the test](src/test/java/java2typescript/jackson/module/DefinitionGeneratorTest.java#L37).

###### Renaming Types using custom (re)naming strategy
To tweak naming TypeScript types for Your specific needs, You can provide an implementation of [TSTypeNamingStrategy](src/main/java/java2typescript/jackson/module/conf/typename/TSTypeNamingStrategy.java), such as [SimpleJacksonTSTypeNamingStrategy](src/main/java/java2typescript/jackson/module/conf/typename/SimpleJacksonTSTypeNamingStrategy.java) (or write Your own) to [Configuration.setNamingStrategy(namingStrategy)](src/main/java/java2typescript/jackson/module/Configuration.java#L61).
To tweak naming TypeScript types for your specific needs, you can provide an implementation of [TSTypeNamingStrategy](src/main/java/java2typescript/jackson/module/conf/typename/TSTypeNamingStrategy.java), such as [SimpleJacksonTSTypeNamingStrategy](src/main/java/java2typescript/jackson/module/conf/typename/SimpleJacksonTSTypeNamingStrategy.java) (or write your own) to [Configuration.setNamingStrategy(namingStrategy)](src/main/java/java2typescript/jackson/module/Configuration.java#L61).

See the test [TypeRenamingWithEnclosingClassTest](src/test/java/java2typescript/jackson/module/TypeRenamingWithEnclosingClassTest.java#L34) and the [expected output of the test](src/test/resources/java2typescript/jackson/module/TypeRenamingWithEnclosingClassTest.twoClassesWithSameName.d.ts#L1).

Expand Down

0 comments on commit b685531

Please sign in to comment.