HHH-6782 - define javadoc groups based on api/spi/internal
This commit is contained in:
Steve Ebersole
parent
fb3566b467
commit
5e8b74d8e8
|
|
@ -13,10 +13,45 @@ ideaModule {
|
|||
javadocBuildDir = dir( buildDirName + "/documentation/javadocs" )
|
||||
|
||||
def List subProjectsToSkipForJavadoc = ['release','documentation'];
|
||||
def List sourceSetsToSkipForJavadoc = ['test','matrix'];
|
||||
|
||||
def copyRightYear = new java.util.GregorianCalendar().get( java.util.Calendar.YEAR );
|
||||
|
||||
task aggregateJavadocs(type: Javadoc) {
|
||||
Set<String> apiPackages = new HashSet<String>()
|
||||
Set<String> spiPackages = new HashSet<String>()
|
||||
Set<String> internalPackages = new HashSet<String>()
|
||||
|
||||
parent.subprojects.each{ subProject->
|
||||
if ( !subProjectsToSkipForJavadoc.contains( subProject.name ) ) {
|
||||
subProject.sourceSets.each { sourceSet ->
|
||||
if ( !sourceSetsToSkipForJavadoc.contains( sourceSet.name ) ) {
|
||||
source sourceSet.java
|
||||
|
||||
if( classpath ) {
|
||||
classpath += sourceSet.classes + sourceSet.compileClasspath
|
||||
}
|
||||
else {
|
||||
classpath = sourceSet.classes + sourceSet.compileClasspath
|
||||
}
|
||||
|
||||
sourceSet.java.each { javaFile ->
|
||||
final String packageName = determinePackageName( sourceSet.java, javaFile );
|
||||
if ( packageName.endsWith( ".internal" ) || packageName.contains( ".internal." ) ) {
|
||||
internalPackages.add( packageName );
|
||||
}
|
||||
else if ( packageName.endsWith( ".spi" ) || packageName.contains( ".spi." ) ) {
|
||||
spiPackages.add( packageName );
|
||||
}
|
||||
else {
|
||||
apiPackages.add( packageName );
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
description = "Build the aggregated JavaDocs for all modules"
|
||||
maxMemory = '512m'
|
||||
destinationDir = javadocBuildDir.dir
|
||||
|
|
@ -28,70 +63,26 @@ task aggregateJavadocs(type: Javadoc) {
|
|||
bottom = "Copyright © 2001-$copyRightYear <a href=\"http://redhat.com\">Red Hat, Inc.</a> All Rights Reserved."
|
||||
use = true
|
||||
links = [ 'http://download.oracle.com/javase/6/docs/api/', 'http://download.oracle.com/javaee/6/api/' ]
|
||||
group(
|
||||
'Core API', [
|
||||
'org.hibernate',
|
||||
'org.hibernate.classic',
|
||||
'org.hibernate.criterion',
|
||||
'org.hibernate.mapping',
|
||||
'org.hibernate.metadata',
|
||||
'org.hibernate.cfg',
|
||||
'org.hibernate.stat'
|
||||
]
|
||||
)
|
||||
group(
|
||||
'Extension SPI', [
|
||||
'org.hibernate.id*',
|
||||
'org.hibernate.connection',
|
||||
'org.hibernate.transaction',
|
||||
'org.hibernate.type',
|
||||
'org.hibernate.dialect*',
|
||||
'org.hibernate.cache*',
|
||||
'org.hibernate.event*',
|
||||
'org.hibernate.property',
|
||||
'org.hibernate.loader*',
|
||||
'org.hibernate.persister*',
|
||||
'org.hibernate.proxy',
|
||||
'org.hibernate.tuple',
|
||||
'org.hibernate.transform',
|
||||
'org.hibernate.collection',
|
||||
'org.hibernate.jdbc',
|
||||
'org.hibernate.usertype'
|
||||
]
|
||||
)
|
||||
group(
|
||||
'Bytecode providers', [
|
||||
'org.hibernate.bytecode*',
|
||||
'org.hibernate.intercept*'
|
||||
]
|
||||
)
|
||||
group (
|
||||
'Infinispan Integration', ['org.hibernate.cache.infinispan*']
|
||||
)
|
||||
group (
|
||||
'JBossCache Integration', ['org.hibernate.cache.jbc*']
|
||||
)
|
||||
group (
|
||||
'Testing Support', ['org.hibernate.junit*']
|
||||
)
|
||||
group( 'API', apiPackages.asList() )
|
||||
group( 'SPI', spiPackages.asList() )
|
||||
group( 'Internal', internalPackages.asList() )
|
||||
group ( 'Testing Support', ['org.hibernate.testing*'] )
|
||||
}
|
||||
}
|
||||
|
||||
parent.subprojects.each{ subProject->
|
||||
if ( !subProjectsToSkipForJavadoc.contains( subProject.name ) ) {
|
||||
subProject.sourceSets.each { set ->
|
||||
if ( !"test".equals( set.name ) ) {
|
||||
source set.java
|
||||
|
||||
if( classpath ) {
|
||||
classpath += set.classes + set.compileClasspath
|
||||
}
|
||||
else {
|
||||
classpath = set.classes + set.compileClasspath
|
||||
}
|
||||
}
|
||||
}
|
||||
String determinePackageName(SourceDirectorySet sourceDirectorySet, File javaFile) {
|
||||
final javaFileAbsolutePath = javaFile.absolutePath;
|
||||
for ( File sourceDirectory : sourceDirectorySet.srcDirs ) {
|
||||
final String sourceDirectoryAbsolutePath = sourceDirectory.absolutePath;
|
||||
if ( javaFileAbsolutePath.startsWith( sourceDirectoryAbsolutePath ) ) {
|
||||
final String javaFileRelativePath = javaFileAbsolutePath.substring(
|
||||
sourceDirectoryAbsolutePath.length() + 1,
|
||||
javaFileAbsolutePath.lastIndexOf( '/' )
|
||||
);
|
||||
return javaFileRelativePath.replace( '/', '.' );
|
||||
}
|
||||
}
|
||||
throw new RuntimeException( "ugh" );
|
||||
}
|
||||
|
||||
aggregateJavadocs.doLast {
|
||||
|
|
|
|||
|
|
@ -27,20 +27,21 @@
|
|||
|
||||
Hibernate provides both<ul>
|
||||
<li>
|
||||
a native API comprised mainly of {@link org.hibernate.SessionFactory} and {@link org.hibernate.Session}
|
||||
a native API comprised centrally around {@link org.hibernate.SessionFactory} and {@link org.hibernate.Session}
|
||||
</li>
|
||||
<li>
|
||||
an implementation of the <a href="">JSR-317</a> Java Persistence API (JPA) specification comprised mainly of
|
||||
{@link org.hibernate.ejb.EntityManagerFactoryImpl} and {@link org.hibernate.ejb.EntityManagerImpl}
|
||||
an implementation of the <a href="http://jcp.org/en/jsr/detail?id=317">JSR-317</a> Java Persistence API (JPA)
|
||||
specification comprised centrally around {@link org.hibernate.ejb.EntityManagerFactoryImpl} and
|
||||
{@link org.hibernate.ejb.EntityManagerImpl} (the Hibernate implementations of
|
||||
{@link javax.persistence.EntityManager} and{@link javax.persistence.EntityManagerFactory}, respectively)
|
||||
</li>
|
||||
</ul>
|
||||
<hr/>
|
||||
|
||||
<h3>Native API</h3>
|
||||
In addition to {@link org.hibernate.SessionFactory} and {@link org.hibernate.Session}, applications using the
|
||||
native API will often need to utilize the following interfaces:<ul>
|
||||
In addition to SessionFactory and Session, applications using the native API will often utilize the following
|
||||
interfaces:<ul>
|
||||
<li>{@link org.hibernate.cfg.Configuration}</li>
|
||||
<li>{@link org.hibernate.Hibernate}</li>
|
||||
<li>{@link org.hibernate.Transaction}</li>
|
||||
<li>{@link org.hibernate.Query}</li>
|
||||
<li>{@link org.hibernate.Criteria}</li>
|
||||
|
|
@ -58,36 +59,23 @@ These interfaces are fully intended to be exposed to application code.
|
|||
The JPA interfaces are all defined by the JPA specification. For details see {@link javax.persistence}
|
||||
<hr/>
|
||||
|
||||
<h3>Extensions</h3>
|
||||
Hibernate defines a number of interfaces that are completely intended to be extendable by application programmers and/or
|
||||
integrators. Listed below is a (not necessarily exhaustive) list of the most commonly utilized extension points:<ul>
|
||||
<li>{@link org.hibernate.EntityNameResolver}</li>
|
||||
<li>{@link org.hibernate.Interceptor} / {@link org.hibernate.EmptyInterceptor}</li>
|
||||
<li>{@link org.hibernate.Transaction} / {@link org.hibernate.transaction.TransactionFactory}</li>
|
||||
<li>{@link org.hibernate.context.CurrentSessionContext}</li>
|
||||
<li>{@link org.hibernate.dialect.Dialect}</li>
|
||||
<li>{@link org.hibernate.dialect.resolver.DialectResolver}</li>
|
||||
<li>{@link org.hibernate.event event listener} interfaces</li>
|
||||
<li>{@link org.hibernate.id.IdentifierGenerator}</li>
|
||||
<li>{@link org.hibernate.tuple.entity.EntityTuplizer} / {@link org.hibernate.tuple.component.ComponentTuplizer}</li>
|
||||
<li>{@link org.hibernate.type.Type} / {@link org.hibernate.usertype}</li>
|
||||
<h3>Package Groups</h3>
|
||||
This documentation groups packages into the following 3 categories:<ul>
|
||||
<li>
|
||||
<strong>API</strong> - classes to which application code will generally bind directly.
|
||||
</li>
|
||||
<li>
|
||||
<strong>SPI</strong> - classes to which application developers or integrators will commonly bind directly in
|
||||
order to develop extensions to Hibernate, or to alter its behavior in some way.
|
||||
</li>
|
||||
<li>
|
||||
<strong>Internal</strong> - classes which are intended only to be used by Hibernate. Use of these classes
|
||||
outside of Hibernate specific use cases is not supported. Moreover, these contracts can change frequently
|
||||
between releases whereas APIs and SPIs are more stable.
|
||||
</li>
|
||||
</ul>
|
||||
Note that there is a large degree of crossover between the notion of extension points and that of an integration SPI (below).
|
||||
<hr/>
|
||||
|
||||
<h3>Integration SPI</h3>
|
||||
Hibernate provides a number of SPIs intended to integrate itself with various third party frameworks or application code to provide
|
||||
additional capabilities. The SPIs fall mainly into 2 categories:<ul>
|
||||
<li>Caching - {@link org.hibernate.cache.RegionFactory}</li>
|
||||
<li>JDBC Connection management - {@link org.hibernate.connection.ConnectionProvider}
|
||||
</ul>
|
||||
Certainly {@link org.hibernate.dialect.Dialect} could fit in here as well, though we chose to list it under extensions since application
|
||||
developers tend to provide extended dialects rather frequently for various reasons.
|
||||
<br/>
|
||||
Another SPI that is not yet exposed but is planned for such is the <em>bytecode provider</em> SPI. See {@link org.hibernate.bytecode}
|
||||
for details.
|
||||
<hr/>
|
||||
|
||||
Complete Hibernate documentation may be found online at <a href="http://docs.jboss.org/hibernate/">http://docs.jboss.org/hibernate/</a>.
|
||||
Complete Hibernate documentation may be found online at <a href="http://docs.jboss.org/hibernate/">http://docs.jboss.org/hibernate/</a>
|
||||
|
||||
</body>
|
||||
Loading…
Reference in New Issue