com.sun.jersey.api.wadl.config.WadlGeneratorConfig Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of ehcache Show documentation
Show all versions of ehcache Show documentation
Ehcache is an open source, standards-based cache used to boost performance,
offload the database and simplify scalability. Ehcache is robust, proven and full-featured and
this has made it the most widely-used Java-based cache.
/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
*
* Copyright (c) 2010-2012 Oracle and/or its affiliates. All rights reserved.
*
* The contents of this file are subject to the terms of either the GNU
* General Public License Version 2 only ("GPL") or the Common Development
* and Distribution License("CDDL") (collectively, the "License"). You
* may not use this file except in compliance with the License. You can
* obtain a copy of the License at
* http://glassfish.java.net/public/CDDL+GPL_1_1.html
* or packager/legal/LICENSE.txt. See the License for the specific
* language governing permissions and limitations under the License.
*
* When distributing the software, include this License Header Notice in each
* file and include the License file at packager/legal/LICENSE.txt.
*
* GPL Classpath Exception:
* Oracle designates this particular file as subject to the "Classpath"
* exception as provided by Oracle in the GPL Version 2 section of the License
* file that accompanied this code.
*
* Modifications:
* If applicable, add the following below the License Header, with the fields
* enclosed by brackets [] replaced by your own identifying information:
* "Portions Copyright [year] [name of copyright owner]"
*
* Contributor(s):
* If you wish your version of this file to be governed by only the CDDL or
* only the GPL Version 2, indicate your decision by adding "[Contributor]
* elects to include this software in this distribution under the [CDDL or GPL
* Version 2] license." If you don't indicate a single choice of license, a
* recipient has the option to distribute your version of this file under
* either the CDDL, the GPL Version 2 or to extend the choice of license to
* its licensees as provided above. However, if you add GPL Version 2 code
* and therefore, elected the GPL Version 2 license, then the option applies
* only if the new code is made subject to such option by the copyright
* holder.
*/
package com.sun.jersey.api.wadl.config;
import java.io.File;
import java.io.InputStream;
import java.util.ArrayList;
import java.util.List;
import java.util.Properties;
import com.sun.jersey.api.core.ResourceConfig;
import com.sun.jersey.server.wadl.WadlGenerator;
import com.sun.jersey.server.wadl.generators.WadlGeneratorApplicationDoc;
import com.sun.jersey.server.wadl.generators.WadlGeneratorGrammarsSupport;
import com.sun.jersey.server.wadl.generators.resourcedoc.WadlGeneratorResourceDocSupport;
/**
* Provides a configured {@link WadlGenerator} with all decorations (the default
* wadl generator decorated by other generators).
*
* Creating a WadlGeneratorConfig
*
* If you want to create an instance at runtime you can configure the
* WadlGenerator class and property names/values. A new instance of the
* Generator is created for each generation action.
*
* The first option would look like this:
*
WadlGeneratorConfig config = WadlGeneratorConfig
.generator( MyWadlGenerator.class )
.prop( "someProperty", "someValue" )
.generator( MyWadlGenerator2.class )
.prop( "someProperty", "someValue" )
.prop( "anotherProperty", "anotherValue" )
.build();
*
*
*
* If you want to specify the {@link WadlGeneratorConfig} in the web.xml you have
* to subclass it and set the servlet init-param {@link ResourceConfig#PROPERTY_WADL_GENERATOR_CONFIG}
* to the name of your subclass. This class might look like this:
* class MyWadlGeneratorConfig extends WadlGeneratorConfig {
public List configure() {
return generator( MyWadlGenerator.class )
.prop( "foo", propValue )
.generator( MyWadlGenerator2.class )
.prop( "bar", propValue2 )
.descriptions();
}
}
*
*
*
*
*
* Configuring the WadlGenerator
*
* The {@link WadlGenerator} properties will be populated with the provided properties like this:
*
* - The types match exactly:
* if the WadlGenerator property is of type org.example.Foo and the
* provided property value is of type org.example.Foo
* - Types that provide a constructor for the provided type (mostly java.lang.String)
* - java.io.InputStream: The {@link InputStream} can e.g. represent a file. The stream is loaded from the
* property value (provided by the {@link WadlGeneratorDescription}) via
* {@link ClassLoader#getResourceAsStream(String)}. It will be closed after {@link WadlGenerator#init()} was called.
*
*
* - Deprected, will be removed in future versions:
* The WadlGenerator property is of type {@link File} and the provided property value is a {@link String}:
* the provided property value can contain the prefix classpath: to denote, that the
* path to the file is relative to the classpath. In this case, the property value is stripped by
* the prefix classpath: and the {@link File} is created via
* new File( generator.getClass().getResource( strippedFilename ).toURI() )
* Notice that the filename is loaded from the classpath in this case, e.g. classpath:test.xml
* refers to a file in the package of the class ({@link WadlGeneratorDescription#getGeneratorClass()}). The
* file reference classpath:/test.xml refers to a file that is in the root of the classpath.
*
*
*
*
*
* Existing {@link WadlGenerator} implementations:
*
*
* - {@link WadlGeneratorApplicationDoc}
* - {@link WadlGeneratorGrammarsSupport}
* - {@link com.sun.jersey.server.wadl.generators.WadlGeneratorJAXBGrammarGenerator}
* - {@link WadlGeneratorResourceDocSupport}
*
*
*
* A common example for a {@link WadlGeneratorConfig} would be this:
*
class MyWadlGeneratorConfig extends WadlGeneratorConfig {
public List configure() {
return generator( WadlGeneratorApplicationDoc.class )
.prop( "applicationDocsStream", "application-doc.xml" )
.generator( WadlGeneratorGrammarsSupport.class )
.prop( "grammarsStream", "application-grammars.xml" )
.generator( WadlGeneratorResourceDocSupport.class )
.prop( "resourceDocStream", "resourcedoc.xml" )
.descriptions();
}
}
*
*
*
* @author Martin Grotzke
* @version $Id: WadlGeneratorConfig.java 5717 2012-06-05 07:51:30Z pavel_bucek $
*/
public abstract class WadlGeneratorConfig {
// private static final Logger LOGGER = Logger.getLogger( WadlGeneratorConfig.class.getName() );
// private WadlGenerator _wadlGenerator;
public WadlGeneratorConfig() {
}
// /**
// * Creates a new WadlGeneratorConfig from the provided wadlGenerator (must already be initialized).
// * @param wadlGenerator the wadl generator to provide, must not be null.
// */
// public WadlGeneratorConfig( WadlGenerator wadlGenerator ) {
// if ( wadlGenerator == null ) {
// throw new IllegalArgumentException( "The wadl generator must not be null." );
// }
// _wadlGenerator = wadlGenerator;
// }
public abstract List configure();
/**
* Create a new instance of {@link WadlGenerator}, based on the {@link WadlGeneratorDescription}s
* provided by {@link #configure()}.
* @return the initialized {@link WadlGenerator}
*/
public WadlGenerator createWadlGenerator() {
WadlGenerator wadlGenerator = null;
final List wadlGeneratorDescriptions = configure();
try {
wadlGenerator = WadlGeneratorLoader.loadWadlGeneratorDescriptions( wadlGeneratorDescriptions );
} catch ( Exception e ) {
throw new RuntimeException( "Could not load wadl generators from wadlGeneratorDescriptions.", e );
}
return wadlGenerator;
}
/**
* Start to build an instance of {@link WadlGeneratorConfig}:
* generator(<class>)
* .prop(<name>, <value>)
* .prop(<name>, <value>)
* .generator(<class>)
* .prop(<name>, <value>)
* .prop(<name>, <value>)
* .build()
* @param generatorClass the class of the wadl generator to configure
* @return an instance of {@link WadlGeneratorConfigDescriptionBuilder}.
*/
public static WadlGeneratorConfigDescriptionBuilder generator( Class generatorClass ) {
return new WadlGeneratorConfigDescriptionBuilder().generator( generatorClass );
}
// /**
// * Start to build an instance of {@link WadlGeneratorConfig}:
// * generator(<generator>).generator(<generator>).build()
// * @param generator the configured wadl generator
// * @return an instance of {@link WadlGeneratorConfigBuilder}.
// */
// public static WadlGeneratorConfigBuilder generator( WadlGenerator generator ) {
// return new WadlGeneratorConfigBuilder().generator( generator );
// }
public static class WadlGeneratorConfigDescriptionBuilder {
private List _descriptions;
private WadlGeneratorDescription _description;
public WadlGeneratorConfigDescriptionBuilder() {
_descriptions = new ArrayList();
}
public WadlGeneratorConfigDescriptionBuilder generator( Class generatorClass ) {
if ( _description != null ) {
_descriptions.add( _description );
}
_description = new WadlGeneratorDescription();
_description.setGeneratorClass( generatorClass );
return this;
}
/**
* Specify the property value for the current {@link WadlGenerator}.
*
* The {@link WadlGenerator} property type can be of any type with
* the following contraints:
*
* If the {@link WadlGenerator} property type is equal to the
* property value type then the property value is set as the
* {@link WadlGenerator} property value.
*
*
* If the {@link WadlGenerator} property type has a constructor with
* a single {@link String} parameter type and the property value is a
* {@link String} then an instance of the property type is constructed
* with the property value and that instance is set as the
* {@link WadlGenerator} property value.
*
*
* If the {@link WadlGenerator} property type is of type {@link File},
* then the specified property value must be a {@link String} starting
* with the prefix classpath: to denote, that the File shall
* be loaded from the classpath like this:
*
new File( generator.getClass().getResource( strippedFilename ).toURI() )
* Notice that the file is loaded as a resource from the classpath
* in this case, therefore classpath:test.xml
* refers to a file in the package of the specified
* <classname>. The file reference
* classpath:/test.xml refers to a file that is in the root
* of the classpath.
*
*
* If the {@link WadlGenerator} property type is of type
* {@link InputStream}, then the specified property value must be a
* {@link String} and the instance of {@link InputStream} is obtained
* with {@link ClassLoader#getResourceAsStream(String)} using the
* current threads context classloader.
* The {@link InputStream} will be closed after
* {@link WadlGenerator#init()} was called and therefore must not be
* closed by the {@link WadlGenerator} using this stream.
*
* @param propName the property name
* @param propValue the stringified property value
* @return this builder instance
*/
public WadlGeneratorConfigDescriptionBuilder prop( String propName, Object propValue ) {
if ( _description.getProperties() == null ) {
_description.setProperties( new Properties() );
}
_description.getProperties().put( propName, propValue );
return this;
}
public List descriptions() {
if ( _description != null ) {
_descriptions.add( _description );
}
return _descriptions;
}
public WadlGeneratorConfig build() {
if ( _description != null ) {
_descriptions.add( _description );
}
return new WadlGeneratorConfigImpl( _descriptions );
}
}
static class WadlGeneratorConfigImpl extends WadlGeneratorConfig {
public List _descriptions;
public WadlGeneratorConfigImpl(
List descriptions) {
_descriptions = descriptions;
}
@Override
public List configure() {
return _descriptions;
}
}
// public static class WadlGeneratorConfigBuilder {
//
// private List _generators;
//
// public WadlGeneratorConfigBuilder() {
// _generators = new ArrayList();
// }
//
// public WadlGeneratorConfigBuilder generator( WadlGenerator generator ) {
// if ( generator == null ) {
// throw new IllegalArgumentException( "The wadl generator must not be null." );
// }
// _generators.add( generator );
// return this;
// }
//
// public WadlGeneratorConfig build() {
// try {
// final WadlGenerator wadlGenerator = WadlGeneratorLoader.loadWadlGenerators( _generators );
// return new WadlGeneratorConfigGeneratorImpl( wadlGenerator ) {
//
// };
// } catch ( Exception e ) {
// throw new RuntimeException( "Could not load wadl generators.", e );
// }
// }
//
// }
// static class WadlGeneratorConfigGeneratorImpl extends WadlGeneratorConfig {
//
// private final WadlGenerator _wadlGenerator;
//
// public WadlGeneratorConfigGeneratorImpl(WadlGenerator wadlGenerator) {
// _wadlGenerator = wadlGenerator;
// }
//
// @Override
// public List configure() {
// throw new UnsupportedOperationException( "Must not be called" );
// }
//
// /* (non-Javadoc)
// * @see com.sun.jersey.server.impl.wadl.config.WadlGeneratorConfig#createWadlGenerator()
// */
// @Override
// public synchronized WadlGenerator createWadlGenerator() {
// return _wadlGenerator;
// }
//
// }
}