gmugra / net.cactusthorn.routing Goto Github PK

SUBJ.

1. Actualize year in the LICENSE file
2. Actualize LICENSE info in the README.md file
3. The LICENSE file should be included in each Jar (in the META-INF)

1. new method addParamConverterProvider instead of addConverter
2. ParamConverterProvider implementations are prioritized over standard converters.
3. ParamConverterProvider implementation can be annotated with javax.annotation.Priority

RoutingConfig must support javax.ws.rs.core.Application as an initialisation source:

ComponentProvider provider = ... ;
RoutingConfig config = RoutingConfig.builder(provider).setApplication(MyApplication.class).build();

Warning: getSingletons() also contains singltones-resources, not only providers.

FYI: https://dennis-xlc.gitbooks.io/restful-java-with-jax-rs-2-0-2rd-edition/content/en/part1/chapter4/path.html (see "Precedence rules")

Using public static methods is not a good style.

FYI : https://docs.oracle.com/javaee/7/api/javax/ws/rs/container/ResourceInfo.html

1. Will need in the futue anyway
2. Now we can change MethodInvoker-class to get javax.ws.rs.container.ResourceInfo in constructor instead of clazz & method

SUBJ.

needs a new method setIOBufferSize to set buffer size, which is used to read/write data from the input/output streams.
The buffer size is now hardcoded with a value of 1024 (which should be the default value).

It is not critical for the major goals of the library, but nice to have. To be more JAX-RS compatible.
(At the moment UriBuilder related methods throw UnsupportedOperationException)
DO TO

1. new class net.cactusthorn.routing.delegate.UriBuilderImpl
2. implement net.cactusthorn.routing.delegate.RuntimeDelegateImpl.createUriBuilder() method
3. implement net.cactusthorn.routing.delegate.LinkImpl.getUriBuilder() method

Specification:

Binds the value(s) of a HTTP header to a resource method parameter, resource class field, or resource class bean property. A default value can be specified using the DefaultValue annotation. The type T of the annotated parameter, field or property must either:

1. Be a primitive type
2. Have a constructor that accepts a single String argument
3. Have a static method named valueOf or fromString that accepts a single String argument (see, for example, > Integer.valueOf(String))
4. Have a registered implementation of ParamConverterProvider JAX-RS extension SPI that returns a ParamConverter instance capable of a "from string" conversion for the type.
5. Be List<T>, Set<T> or SortedSet<T>, where T satisfies 2, 3 or 4 above. The resulting collection is read-only.

Need it to support javax.ws.rs.core.Cookie, which need to solve #15 and #2

Specification RFC 2109:

The syntax for the header is:

cookie = "Cookie:" cookie-version
1*((";" | ",") cookie-value)
cookie-value = NAME "=" VALUE [";" path] [";" domain]
cookie-version = "$Version" "=" value
NAME = attr
VALUE = value
path = "$Path" "=" value
domain = "$Domain" "=" value

4.4 How an Origin Server Interprets the Cookie Header

A user agent returns much of the information in the Set-Cookie header
to the origin server when the Path attribute matches that of a new
request. When it receives a Cookie header, the origin server should
treat cookies with NAMEs whose prefix is $ specially, as an attribute
for the adjacent cookie. The value for such a NAME is to be
interpreted as applying to the lexically (left-to-right) most recent
cookie whose name does not have the $ prefix. If there is no
previous cookie, the value applies to the cookie mechanism as a
whole. For example, consider the cookie

Cookie: $Version="1"; Customer="WILE_E_COYOTE";
$Path="/acme"

$Version applies to the cookie mechanism as a whole (and gives the
version number for the cookie mechanism). $Path is an attribute
whose value (/acme) defines the Path attribute that was used when the
Customer cookie was defined in a Set-Cookie response header.

1. It's easy to get it from HttpServletRequest which is supported by @Context
2. It's not clear: is it need to create the session if it not yet created.

1. move it to net.cactusthorn.routing.body.writer package
2. constructor not need HttpServletReqiest/Response: servlet can inject them in the object later.
3. add second constructor without model-object

Now:

    @GET @Path("upload")
    public Response showUpload(@Context HttpServletRequest request, @Context HttpServletResponse response) {
        Templated templated = new Templated(request, response, "/fileupload.html", null);
        return Response.ok(templated).type(MediaType.TEXT_HTML_TYPE).build();
    }

Should be:

    @GET @Path("upload")
    public Response showUpload() {
        Templated templated = new Templated("/fileupload.html");
        return Response.ok(templated).type(MediaType.TEXT_HTML_TYPE).build();
    }

should work:

@GET
public String getAllOrders(@Context Application app) {
    Map<String, Object> properties = app.getProperties();
}

1. RoutingConfig internally should keep javax.ws.rs.core.Application instance.
2. RoutingConfig should provide methods to specify providers from Class
   1. e.g. addBodyWriter(SimpleGsonBodyWriter.class)
3. RoutingConfig should provide new method putApplicationProperty, related to javax.ws.rs.core.Application -> getProperties() method

https://lgtm.com

TODO

1. fix all alerts
2. add code quality badge

The method was implemeneted as alternative for javax.ws.rs.ApplicationPath annotation.
ApplicationPath javadoc:

Identifies the application path that serves as the base URI for all resource URIs provided by Path.
May only be applied to a subclass of Application.
When published in a Servlet container, the value of the application path may be overridden using a servlet-mapping element in the web.xml.

BUT.
The library is planned to be used only in combination with embadded Servlet container.
So, always exists servlet-mapping. And as result ApplicationPath should always be ignored.

Fact that exists RoutingConfig.applicationPath() method is conceptual bug.

FYI: https://www.logicbig.com/tutorials/java-ee-tutorial/jax-rs/context-resolver.html

e.g.

    @GET
    public String create(@Context Providers providers) {
        ContextResolver<MyContext> cr = providers.getContextResolver(MyContext.class, MediaType.WILDCARD_TYPE);
        ...
    }

TODO

1. implement providers.getContextResolver(...)
2. A ContextResolver implementation may be annotated with @Produces to restrict the media types for which it will be considered suitable. Default: MediaType.WILDCARD_TYPE
3. also it should support @javax.annotation.Priority, like other providers. Why not?

SUBJ.

Also the implementation of javax.ws.rs.ext.Providers should be used internally in the RoutingConfig (instead of collections with providers)

FYI: https://docs.oracle.com/javaee/7/api/javax/ws/rs/ext/Providers.html

SUBJ.

Change the integration of LICENCE file in the JARs
same way with : Gmugra/net.cactusthorn.config#176

Specification:

An implementation MUST include pre-packaged MessageBodyReader and MessageBodyWriter implementations for the following Java and media type combinations:

1. byte[]
   1. All media types ( */* ).
2. java.lang.String
   1. All media types ( */* ).
3. java.io.InputStream
   1. All media types ( */* ).
4. java.io.Reader
   1. All media types ( */* ).
5. java.io.File
   1. All media types ( */* ).
6. javax.activation.DataSource
   1. All media types ( */* ).
7. javax.xml.transform.Source
   1. XML types ( text/xml , application/xml and media types of the form application/*+xml).
8. javax.ws.rs.core.MultivaluedMap<String,String>
   1. Form content ( application/x-www-form-urlencoded ).
9. javax.ws.rs.core.StreamingOutput
   1. All media types ( */* ), MessageBodyWriter only
10. java.lang.Boolean, java.lang.Character, java.lang.Number
    1. Only for text/plain. Corresponding primitive types supported via boxing/unboxing conversion.

FYI:

• 6, 7 are unnecessary.
• 10 is implemented already in some form (ConvertersMessageBodyReader/ObjectMessageBodyWriter)

At the moment, the messages simple hard-coded, which is not nice.
TODO: some simple-to-use solution based on ResourceBundle & MessageFormat

should work e.g.

@POST
@Consumes(MediaType.APPLICATION_FORM_URLENCODED)
public Response processForm(@HeaderParam("X-type") String type, Form form) {
...
}

At the moment @CookieParam support only javax.servlet.http.Cookie which is primitive and wrong accorting to JAX-RS specification.

https://jakarta.ee/specifications/platform/8/apidocs/javax/ws/rs/cookieparam :

public @interface CookieParam

Binds the value of a HTTP cookie to a resource method parameter, resource class field, or resource class bean property. A default value can be specified using the @DefaultValue annotation. The type T of the annotated parameter, field or property must either:

1. Be a primitive type
2. Be javax.ws.rs.core.Cookie
3. Have a constructor that accepts a single String argument
4. Have a static method named valueOf or fromString that accepts a single String argument (see, for example, Integer.valueOf(String))
5. Have a registered implementation of ParamConverterProvider JAX-RS extension SPI that returns a ParamConverter instance capable of a "from string" conversion for the type.
6. Be List<T>, Set<T> or SortedSet<T>, where T satisfies 2, 3, 4 or 5 above. The resulting collection is read-only.

About Exceptions:

if the field or property is
annotated with @HeaderParam or @CookieParam then an implementation MUST generate an instance of
BadRequestException (400 status) that wraps the thrown exception and no entity.

By default, the JAX-RS runtime will automatically support the methods HEAD and OPTIONS if not explicitly implemented. For HEAD, the runtime will invoke the implemented GET method, if present, and ignore the response entity, if set. For OPTIONS, the Allow response header will be set to the set of HTTP methods supported by the resource.

Resource-methods with same http-method & path but different @Produces are not mapped correctly.

e.g.

@Path("/customers")
public class CustomerResource {

   @GET
   @Path("{id}")
   @Produces("application/xml")
   public Customer getCustomerXml(@PathParam("id") int id) {...}

   @GET
   @Path("{id}")
   @Produces("text/plain")
   public String getCustomerText(@PathParam("id") int id) {...}

   @GET
   @Path("{id}")
   @Produces("application/json")
   public Customer getCustomerJson(@PathParam("id") int id) {...}
}

From JSR-339 specification:

Valid parameter types for each of the above annotations are listed in the corresponding Javadoc, however in
general (excluding @Context) the following types are supported:

1. Types for which a ParamConverter is available via a registered ParamConverterProvider. See
   Javadoc for these classes for more information.
2. Primitive types.
3. Types that have a constructor that accepts a single String argument.
4. Types that have a static method named valueOf or fromString with a single String argument
   that return an instance of the type. If both methods are present then valueOf MUST be used unless
   the type is an enum in which case fromString MUST be used.
5. List<T>, Set<T>, or SortedSet<T>, where T satisfies 3 or 4 above. The resulting collection is read-only.

The DefaultValue annotation may be used to supply a default value for some of the above, see the Javadoc
for DefaultValue for usage details and rules for generating a value in the absence of this annotation and
the requested data. The Encoded annotation may be used to disable automatic URI decoding for @MatrixParam, @QueryParam, and @PathParam annotated fields and properties.

A WebApplicationException thrown during construction of field or property values using 3 or 4 above
is processed directly as described in Section 3.3.4. Other exceptions thrown during construction of field
or property values using 3 or 4 above are treated as client errors: if the field or property is annotated with
@MatrixParam, @QueryParam or @PathParam then an implementation MUST generate an instance of
NotFoundException (404 status) that wraps the thrown exception and no entity; if the field or property is
annotated with @HeaderParam or @CookieParam then an implementation MUST generate an instance of
BadRequestException (400 status) that wraps the thrown exception and no entity. Exceptions MUST be
processed as described in Section 3.3.4

So:

1. Simple arrays are not supported at all 😕
2. List<T>, Set<T> and SortedSet<T> only
   1. e.g. Collection<T> is NOT supported
3. valueOf has more priority than fromString, except enums 🤨
4. Exceptions:
   1. @MatrixParam, @QueryParam or @PathParam -> 404
   2. @HeaderParam or @CookieParam -> 400
   3. and what about @FormParam ?

In fact, all of this is a simplification compared to what is currently implemented...

There is an error with this repository's Renovate configuration that needs to be fixed. As a precaution, Renovate will stop PRs until it is resolved.

Error type: Cannot find preset's package (github>whitesource/merge-confidence:beta)

1. test it with Java 11
2. add suport in .travis.yml
3. module-info.java (?)

1. @Context should support javax.ws.rs.core.SecurityContext
2. @Context should NOT support java.security.Principal
3. drop net.cactusthorn.routing.annotation.UserRoles and use javax.annotation.security.RolesAllowed instead

At the moment the library only supports "pre-defined" HttpMethods:
@DELETE, @GET, @HEAD, @OPTIONS, @POST, @PUT, @PATCH
That's not quite right. It should support any "method" which is defined with meta-annotation @HttpMethod.
e.g.

@Target({ElementType.METHOD})
@Retention(RetentionPolicy.RUNTIME)
@HttpMethod("LOCK")
public @interface LOCK {
}

SUBJ.

This issue lists Renovate updates and detected dependencies. Read the Dependency Dashboard docs to learn more.

Rate-Limited

These updates are currently rate-limited. Click on a checkbox below to force their creation now.

• Update dependency org.apache.maven.plugins:maven-release-plugin to v3.0.1
• Update dependency org.glassfish.jaxb:jaxb-runtime to v2.3.9
• Update dependency org.hibernate.validator:hibernate-validator to v6.2.5.Final
• Update dependency org.jacoco:jacoco-maven-plugin to v0.8.11
• Update dependency org.sonatype.plugins:nexus-staging-maven-plugin to v1.6.13
• Update slf4j monorepo to v1.7.36 (org.slf4j:jul-to-slf4j, org.slf4j:slf4j-api)
• Update dependency com.google.code.gson:gson to v2.10.1
• Update dependency org.apache.maven.plugins:maven-assembly-plugin to v3.6.0
• Update dependency org.apache.maven.plugins:maven-checkstyle-plugin to v3.3.1
• Update dependency org.apache.maven.plugins:maven-clean-plugin to v3.3.2
• Update dependency org.apache.maven.plugins:maven-compiler-plugin to v3.12.1
• Update dependency org.apache.maven.plugins:maven-dependency-plugin to v3.6.1
• Update dependency org.apache.maven.plugins:maven-enforcer-plugin to v3.4.1
• Update dependency org.apache.maven.plugins:maven-gpg-plugin to v3.1.0
• Update dependency org.apache.maven.plugins:maven-install-plugin to v3.1.1
• Update dependency org.apache.maven.plugins:maven-jar-plugin to v3.3.0
• Update dependency org.apache.maven.plugins:maven-javadoc-plugin to v3.6.3
• Update dependency org.apache.maven.plugins:maven-jxr-plugin to v3.3.2
• Update dependency org.apache.maven.plugins:maven-project-info-reports-plugin to v3.5.0
• Update dependency org.apache.maven.plugins:maven-resources-plugin to v3.3.1
• Update dependency org.apache.maven.plugins:maven-source-plugin to v3.3.0
• Update dependency org.codehaus.mojo:flatten-maven-plugin to v1.6.0
• Update dependency org.thymeleaf:thymeleaf to v3.1.2.RELEASE
• Update dependency.dagger to v2.51 (com.google.dagger:dagger, com.google.dagger:dagger-compiler)
• Update plugin.test to v3.2.5 (org.apache.maven.plugins:maven-failsafe-plugin, org.apache.maven.plugins:maven-surefire-plugin)
• Update actions/cache action to v4
• Update actions/checkout action to v4
• Update actions/setup-java action to v4
• Update dependency com.puppycrawl.tools:checkstyle to v10
• Update dependency org.glassfish.jaxb:jaxb-runtime to v4
• Update dependency org.hibernate.validator:hibernate-validator to v8
• Update dependency.jetty (major) (org.eclipse.jetty:jetty-servlet, org.eclipse.jetty:jetty-server)
• Update slf4j monorepo to v2 (major) (org.slf4j:jul-to-slf4j, org.slf4j:slf4j-api)
• 🔐 Create all rate-limited PRs at once 🔐

Edited/Blocked

These updates have been manually edited so Renovate will no longer make changes. To discard all commits and start over, click on a checkbox.

• Update dependency com.puppycrawl.tools:checkstyle to v9.3

Open

These updates have all been created already. Click a checkbox below to force a retry/rebase of any.

• Update dependency.jetty to v9.4.54.v20240208 (org.eclipse.jetty:jetty-servlet, org.eclipse.jetty:jetty-server)
• Update dependency ch.qos.logback:logback-classic to v1.5.1
• Update dependency com.github.spotbugs:spotbugs to v4.8.3
• Update dependency com.github.spotbugs:spotbugs-maven-plugin to v4.8.3.1
• Update dependency org.apache.maven.plugins:maven-deploy-plugin to v3.1.1
• Update dependency org.apache.maven.plugins:maven-pmd-plugin to v3.21.2
• Update dependency org.apache.maven.plugins:maven-site-plugin to v3.12.1
• Update junit5 monorepo to v5.10.2 (org.junit.jupiter:junit-jupiter-params, org.junit.jupiter:junit-jupiter-engine, org.junit.jupiter:junit-jupiter-api)
• Update mockito monorepo to v5 (major) (org.mockito:mockito-junit-jupiter, org.mockito:mockito-core)
• Click on this checkbox to rebase all open PRs at once

Ignored or Blocked

These are blocked by an existing closed PR and will not be recreated unless you click a checkbox below.

• Update dependency javax.servlet:javax.servlet-api to v4

Detected dependencies

• Check this box to trigger a request for Renovate to run again on this repository

FYI:

• https://dennis-xlc.gitbooks.io/restful-java-with-jax-rs-2-0-2rd-edition/content/en/part1/chapter4/subresource_locators.html
• https://docs.oracle.com/javaee/7/tutorial/jaxrs-advanced003.htm

When the generic type is required to select a suitable MessageBodyWriter, this class may be used to wrap the entity and capture its generic type.
e.g.

List<String> list = new ArrayList<String>();
GenericEntity<List<String>> entity = new GenericEntity<List<String>>(list) {};
Response response = Response.ok(entity).build();

FYI: need to add support in RoutingServlet

Root resource classes are "plain old Java objects" (POJOs) that are either annotated with @Path or have at least one method annotated with @Path or a request method designator, such as @GET, @PUT, @POST, or @DELETE.

The addResource methods must throw IllegalArgumentException, when parameter is null or not fit requirements for Root resource classes.

FYI: methods annotated with @Path, but with no HTTP method annotation is Subresource Locator. At the moment the library not support it, so such kind of declaration should be ignored.

Convert/check @DefaultValue during the initialization phase:

1. to crash ASAP if it wrong
2. to avoid unnecessary costly converting (because it's reflection) for each request
3. ParamConverter.Lazy concept is not part of this issue

Also be sure:

If the type of the annotated parameter is List, Set or SortedSet then the resulting collection will have a single entry mapped from the supplied default value.

If this annotation is not used and the corresponding meta-data is not present in the request, the value will be an empty collection for List, Set or SortedSet, null for other object types, and the Java-defined default for primitive types.

The literal part of the supplied value (those characters that are not part of a template parameter) is automatically percent encoded to conform to the path production of RFC 3986 section 3.3. Note that percent encoded values are allowed in the literal part of the value, an implementation will recognize such values and will not double encode the '%' character.

RFC 3986:

 path          = path-abempty    ; begins with "/" or is empty
               / path-absolute   ; begins with "/" but not "//"
               / path-noscheme   ; begins with a non-colon segment
               / path-rootless   ; begins with a segment
               / path-empty      ; zero characters

 path-abempty  = *( "/" segment )
 path-absolute = "/" [ segment-nz *( "/" segment ) ]
 path-noscheme = segment-nz-nc *( "/" segment )
 path-rootless = segment-nz *( "/" segment )
 path-empty    = 0<pchar>

 segment       = *pchar
 segment-nz    = 1*pchar
 segment-nz-nc = 1*( unreserved / pct-encoded / sub-delims / "@" )
               ; non-zero-length segment without any colon ":"

 pchar         = unreserved / pct-encoded / sub-delims / ":" / "@"

 unreserved    = ALPHA / DIGIT / "-" / "." / "_" / "~"
 sub-delims    = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "="

HttpServletRequest#getPathInfo:

Returns:
a String, decoded by the web container, specifying extra path information that comes after the servlet path but before the query string in the request URL; or null if the URL does not have any extra path information

FYI: net.cactusthorn.routing.uri.UriComponentEncoder

1. rename: EntryPointScanner -> ResourceScanner
2. rename: EntryPoint -> Resource
3. all classes related to new ResourceScanner class should be in sub-package resource
4. all methods in other classes should be renamed accorting the change. (e.g. RoutingConfig: addEntryPoint -> addResource )

At the moment, it's not about 100% full implementation.

Next methods not need to be implemented:

• getMatchedResources()
• getMatchedURIs()
• getMatchedURIs(boolean decode)
• getPathSegments()
• getPathSegments(boolean decode)