search

eclipse-vertx / vert.x

Vert.x is a tool-kit for building reactive applications on the JVM
http://vertx.io
Other
14.25k stars 2.07k forks source link

Fix Javadoc for subRouter #4516

Open janfengler opened 1 year ago

janfengler commented 1 year ago

From our emails:

Indeed, that is a javadoc bug. It used to be like that before the sub routing got a major refactor long ago. Can you open an issue to review it.

Basically, the "before" is incorrect. Any handlers can be added before, yet only 1 routes is allowed per route.

---- On Wed, 12 Oct 2022 08:58:54 +0200 Jan Fengler Jan.Fengler@adviqo.com wrote ---

Hi Paulo,

this is the javadoc for the subrouter-Method (from [https://vertx.io/docs/apidocs/io/vertx/reactivex/ext/web/Route.html#subRouter-io.vertx.reactivex.ext.web.Router-](https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fvertx.io%2Fdocs%2Fapidocs%2Fio%2Fvertx%2Freactivex%2Fext%2Fweb%2FRoute.html%23subRouter-io.vertx.reactivex.ext.web.Router-&data=05%7C01%7Cjan.fengler%40adviqo.com%7C75b1abdb5c4c418eafe108daac1fd377%7Ccc95c3cf2733459eac760efef936135c%7C0%7C0%7C638011550333895697%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=wt3ctISIRFMGG%2BghgHBeqWm75e1gADaUgWMkaLNFZn8%3D&reserved=0)):

public [Route](https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fvertx.io%2Fdocs%2Fapidocs%2Fio%2Fvertx%2Freactivex%2Fext%2Fweb%2FRoute.html&data=05%7C01%7Cjan.fengler%40adviqo.com%7C75b1abdb5c4c418eafe108daac1fd377%7Ccc95c3cf2733459eac760efef936135c%7C0%7C0%7C638011550333895697%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=huyBRcDheLkZOeARYbbBFHltWVrueFrUSJusDJ2sqL8%3D&reserved=0) sub[Router](https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fvertx.io%2Fdocs%2Fapidocs%2Fio%2Fvertx%2Freactivex%2Fext%2Fweb%2FRouter.html&data=05%7C01%7Cjan.fengler%40adviqo.com%7C75b1abdb5c4c418eafe108daac1fd377%7Ccc95c3cf2733459eac760efef936135c%7C0%7C0%7C638011550333895697%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=h0%2B82rX%2Fc31%2BKk4%2FCuF2LoY6pce0846c5YHjpdCjQus%3D&reserved=0)(Router subRouter)

Use a (sub) [Router](https://eur03.safelinks.protection.outlook.com/?url=https%3A%2F%2Fvertx.io%2Fdocs%2Fapidocs%2Fio%2Fvertx%2Freactivex%2Fext%2Fweb%2FRouter.html&data=05%7C01%7Cjan.fengler%40adviqo.com%7C75b1abdb5c4c418eafe108daac1fd377%7Ccc95c3cf2733459eac760efef936135c%7C0%7C0%7C638011550333895697%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=h0%2B82rX%2Fc31%2BKk4%2FCuF2LoY6pce0846c5YHjpdCjQus%3D&reserved=0) as a handler. There are several requirements to be fulfilled for this to be accepted.

    The route path must end with a wild card
    Parameters are allowed but full regex patterns not
    No other handler can be registered before or after this call (but they can on a new route object for the same path)
    Only 1 router per path object

Parameters:
    subRouter - the router to add
Returns:
    a reference to this, so the API can be used fluently

AFAIC currently say, your first proposal seems to work (test ongoing, but no big difference to our own "solution"), but the third bullet point from the javadoc above seems misleading then, because "No other handler can be registered BEFORE or after this call...". Is'nt  that what's happening (and the documentation must be modified) or is the proposed solution using the mentioned exception via a new route object?

Thx
  Jan
tsegismont commented 1 year ago

I think this should be filed to the vertx-web repository instead