We were just talking about building a list of all JBoss AS public API calls. This will be used to document the public API versus what is considered private (we will include only the public API in this "public api" documentation). One idea mentioned already is that we could use an annotation (e.g. something like @publicAPI mentioned elsewhere http://www.opends.org/promoted-builds/2.0.0-RC1/javadoc/org/opends/server...). We would then build the "public API" documentation based on the @publicAPI annotations (the how to be determined). We might want to also include a @privateAPI tag, for source files that contain a mix of public and private API (or maybe we should move anything private into separate modules).

+1 for annotations as we could also flag illegal usages at compile time via an annotations compiler. On Jun 1, 2009, at 17:00, David M. Lloyd wrote: > On 06/01/2009 03:19 PM, Scott Marlow wrote: >> We were just talking about building a list of all JBoss AS public >> API calls. This will be used to document the public API versus >> what is considered private (we will include only the public API in >> this "public api" documentation). >> One idea mentioned already is that we could use an annotation >> (e.g. something like @publicAPI mentioned elsewhere http://www.opends.org/promoted-builds/2.0.0-RC1/javadoc/org/opends/server...) >> . We would then build the "public API" documentation based on the >> @publicAPI annotations (the how to be determined). >> We might want to also include a @privateAPI tag, for source files >> that contain a mix of public and private API (or maybe we should >> move anything private into separate modules). > > The way I traditionally tackle this is by using package-private > access for non-API stuff in the API package. Otherwise, a taglet > would be a great way to do this (annotations are probably > overkill). Javadoc may be an old technology but it's still decent. > > One thing I also have for Remoting 3 is a set of javadoc tags that > I can stick on a class or interface which causes a generic > explanation to be appended to the javadoc (like "This interface is > intended to be implemented by the end user" or "This interface is > intended for service providers, so new methods may be added without > notice", etc). I can provide a link as soon as I get around to > getting the javadoc published for 3.1. > > - DML > _______________________________________________ > jboss-development mailing list > jboss-development(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/jboss-development

Illegal usages such as what? - DML On 06/01/2009 04:04 PM, Emmanuel Bernard wrote: > +1 for annotations as we could also flag illegal usages at compile > time via an annotations compiler. > > On Jun 1, 2009, at 17:00, David M. Lloyd wrote: > >> On 06/01/2009 03:19 PM, Scott Marlow wrote: >>> We were just talking about building a list of all JBoss AS public >>> API calls. This will be used to document the public API versus >>> what is considered private (we will include only the public API in >>> this "public api" documentation). >>> One idea mentioned already is that we could use an annotation (e.g. >>> something like @publicAPI mentioned elsewhere >>> http://www.opends.org/promoted-builds/2.0.0-RC1/javadoc/org/opends/server...). >>> We would then build the "public API" documentation based on the >>> @publicAPI annotations (the how to be determined). >>> We might want to also include a @privateAPI tag, for source files >>> that contain a mix of public and private API (or maybe we should >>> move anything private into separate modules). >> >> The way I traditionally tackle this is by using package-private >> access for non-API stuff in the API package. Otherwise, a taglet >> would be a great way to do this (annotations are probably >> overkill). Javadoc may be an old technology but it's still decent. >> >> One thing I also have for Remoting 3 is a set of javadoc tags that I >> can stick on a class or interface which causes a generic explanation >> to be appended to the javadoc (like "This interface is intended to >> be implemented by the end user" or "This interface is intended for >> service providers, so new methods may be added without notice", >> etc). I can provide a link as soon as I get around to getting the >> javadoc published for 3.1. >> >> - DML >> _______________________________________________ >> jboss-development mailing list >> jboss-development(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/jboss-development > > _______________________________________________ > jboss-development mailing list > jboss-development(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/jboss-development _______________________________________________ jboss-development mailing list jboss-development(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/jboss-development

But of course in AS 6, private APIs won't be accessible to customer deployments anyway, since we'll have nice API/impl separation and we'll be fully modularized. Right guys? RIGHT?!? - DML On 06/02/2009 09:36 PM, Scott Marlow wrote: > One illegal usage might be detecting that a private (JBoss > internal) API was used by a customer application. This would be > useful for our customers to know as private API can change > unexpectedly from release to release. > Applications that use private APIs will need more refactoring > during migration to a new AS release. > Perhaps we could also have a usage check for unsupported APIs (some > projects have contributions that may be considered experimental). > David M. Lloyd wrote: >> Illegal usages such as what? >> >> - DML >> >> On 06/01/2009 04:04 PM, Emmanuel Bernard wrote: >>> +1 for annotations as we could also flag illegal usages at >>> compile time via an annotations compiler. >>> >>> On Jun 1, 2009, at 17:00, David M. Lloyd wrote: >>> >>>> On 06/01/2009 03:19 PM, Scott Marlow wrote: >>>>> We were just talking about building a list of all JBoss AS >>>>> public API calls. This will be used to document the public API >>>>> versus what is considered private (we will include only the >>>>> public API in this "public api" documentation). >>>>> One idea mentioned already is that we could use an annotation >>>>> (e.g. something like @publicAPI mentioned elsewhere http://www.opends.org/promoted-builds/2.0.0-RC1/javadoc/org/opends/server...) >>>>> . We would then build the "public API" documentation based on >>>>> the @publicAPI annotations (the how to be determined). >>>>> We might want to also include a @privateAPI tag, for source >>>>> files that contain a mix of public and private API (or maybe we >>>>> should move anything private into separate modules). >>>> >>>> The way I traditionally tackle this is by using package-private >>>> access for non-API stuff in the API package. Otherwise, a >>>> taglet would be a great way to do this (annotations are probably >>>> overkill). Javadoc may be an old technology but it's still >>>> decent. >>>> >>>> One thing I also have for Remoting 3 is a set of javadoc tags >>>> that I can stick on a class or interface which causes a generic >>>> explanation to be appended to the javadoc (like "This interface >>>> is intended to be implemented by the end user" or "This >>>> interface is intended for service providers, so new methods may >>>> be added without notice", etc). I can provide a link as soon as >>>> I get around to getting the javadoc published for 3.1. >>>> >>>> - DML >>>> _______________________________________________ >>>> jboss-development mailing list >>>> jboss-development(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/jboss-development >>> >>> _______________________________________________ >>> jboss-development mailing list >>> jboss-development(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/jboss-development >> _______________________________________________ >> jboss-development mailing list >> jboss-development(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/jboss-development > _______________________________________________ > jboss-development mailing list > jboss-development(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/jboss-development _______________________________________________ jboss-development mailing list jboss-development(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/jboss-development

Theoretically, it would be completely transparent for regular JavaEE-style deployment types at least. For plain JAR deployments I guess it would depend on how we decide to implement it - would dependencies be explicitly listed? Would we have a base classpath that is supplemented by user-specified dependencies? Etc. Right now it appears that nobody is pursuing modularization. Hopefully we can find a way to get this prioritized. - DML On 06/03/2009 05:28 PM, Emmanuel Bernard wrote: > Naive question, wouldn't it be impractical/annoying to enforce that? > > On Jun 3, 2009, at 08:43, David M. Lloyd wrote: > >> But of course in AS 6, private APIs won't be accessible to customer >> deployments anyway, since we'll have nice API/impl separation and >> we'll be fully modularized. >> >> Right guys? >> >> RIGHT?!? >> >> - DML >>

Naive question, wouldn't it be impractical/annoying to enforce that?

On Jun 3, 2009, at 08:43, David M. Lloyd wrote: > But of course in AS 6, private APIs won't be accessible to customer > deployments anyway, since we'll have nice API/impl separation and > we'll be fully modularized. > > Right guys? > > RIGHT?!? > > - DML > > On 06/02/2009 09:36 PM, Scott Marlow wrote: >> One illegal usage might be detecting that a private (JBoss internal) >> API was used by a customer application. This would be useful for >> our customers to know as private API can change unexpectedly from >> release to release. >> Applications that use private APIs will need more refactoring during >> migration to a new AS release. >> Perhaps we could also have a usage check for unsupported APIs (some >> projects have contributions that may be considered experimental). >> David M. Lloyd wrote: >>> Illegal usages such as what? >>> >>> - DML >>> >>> On 06/01/2009 04:04 PM, Emmanuel Bernard wrote: >>>> +1 for annotations as we could also flag illegal usages at compile >>>> time via an annotations compiler. >>>> >>>> On Jun 1, 2009, at 17:00, David M. Lloyd wrote: >>>> >>>>> On 06/01/2009 03:19 PM, Scott Marlow wrote: >>>>>> We were just talking about building a list of all JBoss AS >>>>>> public API calls. This will be used to document the public API >>>>>> versus what is considered private (we will include only the >>>>>> public API in this "public api" documentation). >>>>>> One idea mentioned already is that we could use an annotation >>>>>> (e.g. something like @publicAPI mentioned elsewhere >>>>>> http://www.opends.org/promoted-builds/2.0.0-RC1/javadoc/org/opends/server...). >>>>>> We would then build the "public API" documentation based on the >>>>>> @publicAPI annotations (the how to be determined). >>>>>> We might want to also include a @privateAPI tag, for source >>>>>> files that contain a mix of public and private API (or maybe we >>>>>> should move anything private into separate modules). >>>>> >>>>> The way I traditionally tackle this is by using package-private >>>>> access for non-API stuff in the API package. Otherwise, a taglet >>>>> would be a great way to do this (annotations are probably >>>>> overkill). Javadoc may be an old technology but it's still decent. >>>>> >>>>> One thing I also have for Remoting 3 is a set of javadoc tags >>>>> that I can stick on a class or interface which causes a generic >>>>> explanation to be appended to the javadoc (like "This interface >>>>> is intended to be implemented by the end user" or "This interface >>>>> is intended for service providers, so new methods may be added >>>>> without notice", etc). I can provide a link as soon as I get >>>>> around to getting the javadoc published for 3.1. >>>>> >>>>> - DML >>>>> _______________________________________________ >>>>> jboss-development mailing list >>>>> jboss-development(a)lists.jboss.org >>>>> https://lists.jboss.org/mailman/listinfo/jboss-development >>>> >>>> _______________________________________________ >>>> jboss-development mailing list >>>> jboss-development(a)lists.jboss.org >>>> https://lists.jboss.org/mailman/listinfo/jboss-development >>> _______________________________________________ >>> jboss-development mailing list >>> jboss-development(a)lists.jboss.org >>> https://lists.jboss.org/mailman/listinfo/jboss-development >> _______________________________________________ >> jboss-development mailing list >> jboss-development(a)lists.jboss.org >> https://lists.jboss.org/mailman/listinfo/jboss-development > _______________________________________________ > jboss-development mailing list > jboss-development(a)lists.jboss.org > https://lists.jboss.org/mailman/listinfo/jboss-development _______________________________________________ jboss-development mailing list jboss-development(a)lists.jboss.org https://lists.jboss.org/mailman/listinfo/jboss-development

One illegal usage might be detecting that a private (JBoss internal) API was used by a customer application. This would be useful for our customers to know as private API can change unexpectedly from release to release. Applications that use private APIs will need more refactoring during migration to a new AS release. Perhaps we could also have a usage check for unsupported APIs (some projects have contributions that may be considered experimental). David M. Lloyd wrote: > Illegal usages such as what? > > - DML > > On 06/01/2009 04:04 PM, Emmanuel Bernard wrote: >> +1 for annotations as we could also flag illegal usages at compile >> time via an annotations compiler. >> >> On Jun 1, 2009, at 17:00, David M. Lloyd wrote: >> >>> On 06/01/2009 03:19 PM, Scott Marlow wrote: >>>> We were just talking about building a list of all JBoss AS public >>>> API calls. This will be used to document the public API versus >>>> what is considered private (we will include only the public API in >>>> this "public api" documentation). >>>> One idea mentioned already is that we could use an annotation >>>> (e.g. something like @publicAPI mentioned elsewhere >>>> http://www.opends.org/promoted-builds/2.0.0-RC1/javadoc/org/opends/server...). >>>> We would then build the "public API" documentation based on the >>>> @publicAPI annotations (the how to be determined). >>>> We might want to also include a @privateAPI tag, for source files >>>> that contain a mix of public and private API (or maybe we should >>>> move anything private into separate modules). >>> >>> The way I traditionally tackle this is by using package-private >>> access for non-API stuff in the API package. Otherwise, a taglet >>> would be a great way to do this (annotations are probably >>> overkill). Javadoc may be an old technology but it's still decent. >>> >>> One thing I also have for Remoting 3 is a set of javadoc tags that >>> I can stick on a class or interface which causes a generic >>> explanation to be appended to the javadoc (like "This interface is >>> intended to be implemented by the end user" or "This interface is >>> intended for service providers, so new methods may be added without >>> notice", etc). I can provide a link as soon as I get around to >>> getting the javadoc published for 3.1. >>> >>> - DML

Anil Saldhana wrote: > If you look at the Java EE javadoc bundle for example - there is no > clear separation between what is applicable to SPI implementers, > container vendors and JavaEE users. > > We really need documentation on API that is for public usage ( both > users as well as JBoss system integrators) and of course the private > api. > When we mark an API as public, what are we trying to say to application developers? I have the same question about why we mark an API as private. One possible answer for public API, is that customers are expected to call public API. Another comment that we might make about public API, is that it is not expected to change often (but may). We might want to say that an API is marked private if it can change more often (perhaps in a minor release cycle). We need to establish some rules that we can live with (for a number of years) about the implied contract behind the public/private API annotations. We could even do something similar to the Open Directory Server link that I referenced earlier (http://www.opends.org/promoted-builds/2.0.0-RC1/javadoc/org/opends/server...). The OpenDS javadoc is pretty clear on the contractual meaning of their PublicAPI annotation. Anil, great suggestion about adding more documentation (we have seen that point raised repeatedly in the last few days). Not everyone in the community is going to be as genius as the original implementors of feature X. The same is true for internal engineers (development/qa/support). I would like to see these (internal/external) engineers succeed in their tasks. Improving the Javadoc, will lower the barrier for these folks to achieve success in their projects. Hopefully, in a few days, we will have an understanding of how to start approaching the way that we mark public/private API in our code base (so we can make some progress in that area). Thanks for your support! :) > Scott Marlow wrote: >> One illegal usage might be detecting that a private (JBoss internal) >> API was used by a customer application. This would be useful for >> our customers to know as private API can change unexpectedly from >> release to release. >> >> Applications that use private APIs will need more refactoring during >> migration to a new AS release. >> >> Perhaps we could also have a usage check for unsupported APIs (some >> projects have contributions that may be considered experimental). >> David M. Lloyd wrote: >>> Illegal usages such as what? >>> >>> - DML >>> >>> On 06/01/2009 04:04 PM, Emmanuel Bernard wrote: >>>> +1 for annotations as we could also flag illegal usages at compile >>>> time via an annotations compiler. >>>> >>>> On Jun 1, 2009, at 17:00, David M. Lloyd wrote: >>>> >>>>> On 06/01/2009 03:19 PM, Scott Marlow wrote: >>>>>> We were just talking about building a list of all JBoss AS >>>>>> public API calls. This will be used to document the public API >>>>>> versus what is considered private (we will include only the >>>>>> public API in this "public api" documentation). >>>>>> One idea mentioned already is that we could use an annotation >>>>>> (e.g. something like @publicAPI mentioned elsewhere >>>>>> http://www.opends.org/promoted-builds/2.0.0-RC1/javadoc/org/opends/server...). >>>>>> We would then build the "public API" documentation based on the >>>>>> @publicAPI annotations (the how to be determined). >>>>>> We might want to also include a @privateAPI tag, for source >>>>>> files that contain a mix of public and private API (or maybe we >>>>>> should move anything private into separate modules). >>>>> >>>>> The way I traditionally tackle this is by using package-private >>>>> access for non-API stuff in the API package. Otherwise, a taglet >>>>> would be a great way to do this (annotations are probably >>>>> overkill). Javadoc may be an old technology but it's still decent. >>>>> >>>>> One thing I also have for Remoting 3 is a set of javadoc tags >>>>> that I can stick on a class or interface which causes a generic >>>>> explanation to be appended to the javadoc (like "This interface >>>>> is intended to be implemented by the end user" or "This interface >>>>> is intended for service providers, so new methods may be added >>>>> without notice", etc). I can provide a link as soon as I get >>>>> around to getting the javadoc published for 3.1. >>>>> >>>>> - DML

> > One thing I also have for Remoting 3 is a set of javadoc tags that I > can stick on a class or interface which causes a generic explanation > to be appended to the javadoc (like "This interface is intended to be > implemented by the end user" or "This interface is intended for > service providers, so new methods may be added without notice", > etc). I can provide a link as soon as I get around to getting the > javadoc published for 3.1. The advantage though of an annotation, is that we can then generate a compendium of all public apis for all of our software. You can't do that with a note in the javadoc.