/*
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
*
* under the terms of the GNU General Public License version 2 only, as
* published by the Free Software Foundation. Oracle designates this
* particular file as subject to the "Classpath" exception as provided
* by Oracle in the LICENSE file that accompanied this code.
*
* This code is distributed in the hope that it will be useful, but WITHOUT
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
* version 2 for more details (a copy is included in the LICENSE file that
* accompanied this code).
*
* You should have received a copy of the GNU General Public License version
* 2 along with this work; if not, write to the Free Software Foundation,
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
*
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
* or visit www.oracle.com if you need additional information or have any
* questions.
*/
/**
* The Service Provider Interface (SPI) mechanism that generates <code>SyncProvider</code>
* instances to be used by disconnected <code>RowSet</code> objects.
* The <code>SyncProvider</code> instances in turn provide the
* <code>javax.sql.RowSetReader</code> object the <code>RowSet</code> object
* needs to populate itself with data and the
* <code>javax.sql.RowSetWriter</code> object it needs to
* propagate changes to its
* data back to the underlying data source.
* <P>
* Because the methods in the <code>SyncFactory</code> class are all static,
* there is only one <code>SyncFactory</code> object
* per Java VM at any one time. This ensures that there is a single source from which a
* <code>RowSet</code> implementation can obtain its <code>SyncProvider</code>
* implementation.
* <p>
* <h3>1.0 Overview</h3>
* The <code>SyncFactory</code> class provides an internal registry of available
* synchronization provider implementations (<code>SyncProvider</code> objects).
* This registry may be queried to determine which
* synchronization providers are available.
* The following line of code gets an enumeration of the providers currently registered.
* <PRE>
* java.util.Enumeration e = SyncFactory.getRegisteredProviders();
* </PRE>
* All standard <code>RowSet</code> implementations must provide at least two providers:
* <UL>
* <LI>an optimistic provider for use with a <code>CachedRowSet</code> implementation
* or an implementation derived from it
* <LI>an XML provider, which is used for reading and writing XML, such as with
* <code>WebRowSet</code> objects
* </UL>
* Note that the JDBC RowSet Implementations include the <code>SyncProvider</code>
* implemtations <code>RIOptimisticProvider</code> and <code>RIXmlProvider</code>,
* which satisfy this requirement.
* <P>
* The <code>SyncFactory</code> class provides accessor methods to assist
* applications in determining which synchronization providers are currently
* registered with the <code>SyncFactory</code>.
* <p>
* Other methods let <code>RowSet</code> persistence providers be
* registered or de-registered with the factory mechanism. This
* allows additional synchronization provider implementations to be made
* available to <code>RowSet</code> objects at run time.
* <p>
* Applications can apply a degree of filtering to determine the level of
* synchronization that a <code>SyncProvider</code> implementation offers.
* The following criteria determine whether a provider is
* made available to a <code>RowSet</code> object:
* <ol>
* <li>If a particular provider is specified by a <code>RowSet</code> object, and
* the <code>SyncFactory</code> does not contain a reference to this provider,
* a <code>SyncFactoryException</code> is thrown stating that the synchronization
* provider could not be found.
* <p>
* <li>If a <code>RowSet</code> implementation is instantiated with a specified
* provider and the specified provider has been properly registered, the
* requested provider is supplied. Otherwise a <code>SyncFactoryException</code>
* is thrown.
* <p>
* <li>If a <code>RowSet</code> object does not specify a
* <code>SyncProvider</code> implementation and no additional
* <code>SyncProvider</code> implementations are available, the reference
* implementation providers are supplied.
* </ol>
* <h3>2.0 Registering <code>SyncProvider</code> Implementations</h3>
* <p>
* Both vendors and developers can register <code>SyncProvider</code>
* implementations using one of the following mechanisms.
* <ul>
* <LI><B>Using the command line</B><BR>
* The name of the provider is supplied on the command line, which will add
* the provider to the system properties.
* For example:
* <PRE>
* -Drowset.provider.classname=com.fred.providers.HighAvailabilityProvider
* </PRE>
* <li><b>Using the Standard Properties File</b><BR>
* The reference implementation is targeted
* to ship with J2SE 1.5, which will include an additional resource file
* that may be edited by hand. Here is an example of the properties file
* included in the reference implementation:
* <PRE>
* #Default JDBC RowSet sync providers listing
* #
*
* # Optimistic synchronization provider
* rowset.provider.classname.0=com.sun.rowset.providers.RIOptimisticProvider
* rowset.provider.vendor.0=Oracle Corporation
* rowset.provider.version.0=1.0
*
* # XML Provider using standard XML schema
* rowset.provider.classname.1=com.sun.rowset.providers.RIXMLProvider
* rowset.provider.vendor.1=Oracle Corporation
* rowset.provider.version.1=1.0
* </PRE>
* The <code>SyncFactory</code> checks this file and registers the
* <code>SyncProvider</code> implementations that it contains. A
* developer or vendor can add other implementations to this file.
* For example, here is a possible addition:
* <PRE>
* rowset.provider.classname.2=com.fred.providers.HighAvailabilityProvider
* rowset.provider.vendor.2=Fred, Inc.
* rowset.provider.version.2=1.0
* </PRE>
* <p>
* <li><b>Using a JNDI Context</b><BR>
* Available providers can be registered on a JNDI
* context, and the <code>SyncFactory</code> will attempt to load
* <code>SyncProvider</code> implementations from that JNDI context.
* For example, the following code fragment registers a provider implementation
* on a JNDI context. This is something a deployer would normally do. In this
* example, <code>MyProvider</code> is being registered on a CosNaming
* namespace, which is the namespace used by J2EE resources.
* <PRE>
* import javax.naming.*;
*
* Hashtable svrEnv = new Hashtable();
* srvEnv.put(Context.INITIAL_CONTEXT_FACTORY, "CosNaming");
*
* Context ctx = new InitialContext(svrEnv);
* com.fred.providers.MyProvider = new MyProvider();
* ctx.rebind("providers/MyProvider", syncProvider);
* </PRE>
* </ul>
* Next, an application will register the JNDI context with the
* <code>SyncFactory</code> instance. This allows the <code>SyncFactory</code>
* to browse within the JNDI context looking for <code>SyncProvider</code>
* implementations.
* <PRE>
* Hashtable appEnv = new Hashtable();
* appEnv.put(Context.INITIAL_CONTEXT_FACTORY, "CosNaming");
* Context ctx = new InitialContext(appEnv);
*
* SyncFactory.registerJNDIContext(ctx);
* </PRE>
* If a <code>RowSet</code> object attempts to obtain a <code>MyProvider</code>
* object, the <code>SyncFactory</code> will try to locate it. First it searches
* for it in the system properties, then it looks in the resource files, and
* finally it checks the JNDI context that has been set. The <code>SyncFactory</code>
* instance verifies that the requested provider is a valid extension of the
* <code>SyncProvider</code> abstract class and then gives it to the
* <code>RowSet</code> object. In the following code fragment, a new
* <code>CachedRowSet</code> object is created and initialized with
* <i>env</i>, which contains the binding to <code>MyProvider</code>.
* <PRE>
* Hashtable env = new Hashtable();
* env.put(SyncFactory.ROWSET_SYNC_PROVIDER, "com.fred.providers.MyProvider");
* CachedRowSet crs = new com.sun.rowset.CachedRowSetImpl(env);
* </PRE>
* Further details on these mechanisms are available in the
* <code>javax.sql.rowset.spi</code> package specification.
*
* @author Jonathan Bruce
* @see javax.sql.rowset.spi.SyncProvider
* @see javax.sql.rowset.spi.SyncFactoryException
*/
public class SyncFactory {
/**
* Creates a new <code>SyncFactory</code> object, which is the singleton
* instance.
* Having a private constructor guarantees that no more than
* one <code>SyncProvider</code> object can exist at a time.
*/
private SyncFactory() {
}
/**
* The standard property-id for a synchronization provider implementation
* name.
*/
"rowset.provider.classname";
/**
* The standard property-id for a synchronization provider implementation
* vendor name.
*/
"rowset.provider.vendor";
/**
* The standard property-id for a synchronization provider implementation
* version tag.
*/
"rowset.provider.version";
/**
* The standard resource file name.
*/
/**
* The RI Optimistic Provider.
*/
"com.sun.rowset.providers.RIOptimisticProvider";
/**
* Permission required to invoke setJNDIContext and setLogger
*/
new SQLPermission("setSyncFactory");
/**
* The initial JNDI context where <code>SyncProvider</code> implementations can
* be stored and from which they can be invoked.
*/
/**
* The <code>Logger</code> object to be used by the <code>SyncFactory</code>.
*/
/**
*
*/
/**
* The registry of available <code>SyncProvider</code> implementations.
* See section 2.0 of the class comment for <code>SyncFactory</code> for an
* explanation of how a provider can be added to this registry.
*/
/**
* Internal sync object used to maintain the SPI as a singleton
*/
/**
* Internal PrintWriter field for logging facility
*/
/**
* Adds the the given synchronization provider to the factory register. Guidelines
* are provided in the <code>SyncProvider</code> specification for the
* required naming conventions for <code>SyncProvider</code>
* implementations.
* <p>
* Synchronization providers bound to a JNDI context can be
* registered by binding a SyncProvider instance to a JNDI namespace.
* <ul>
* <pre>
* SyncProvider p = new MySyncProvider();
* InitialContext ic = new InitialContext();
* ic.bind ("jdbc/rowset/MySyncProvider", p);
* </pre>
* </ul>
* Furthermore, an initial JNDI context should be set with the
* <code>SyncFactory</code> using the <code>setJNDIContext</code> method.
* The <code>SyncFactory</code> leverages this context to search for
* available <code>SyncProvider</code> objects bound to the JNDI
* context and its child nodes.
*
* @param providerID A <code>String</code> object with the unique ID of the
* synchronization provider being registered
* @throws SyncFactoryException if an attempt is made to supply an empty
* or null provider name
* @see #setJNDIContext
*/
throws SyncFactoryException {
}
/**
* Returns the <code>SyncFactory</code> singleton.
*
* @return the <code>SyncFactory</code> instance
*/
/*
* Using Initialization on Demand Holder idiom as
* Effective Java 2nd Edition,ITEM 71, indicates it is more performant
* than the Double-Check Locking idiom.
*/
return SyncFactoryHolder.factory;
}
/**
* Removes the designated currently registered synchronization provider from the
* Factory SPI register.
*
* @param providerID The unique-id of the synchronization provider
* @throws SyncFactoryException If an attempt is made to
* unregister a SyncProvider implementation that was not registered.
*/
throws SyncFactoryException {
}
}
// Local implementation class names and keys from Properties
// file, translate names into Class objects using Class.forName
// and store mappings
if (implementations == null) {
implementations = new Hashtable();
try {
// check if user is supplying his Synchronisation Provider
// Implementation if not using Oracle's implementation.
// properties.load(new FileInputStream(ROWSET_PROPERTIES));
// The rowset.properties needs to be in jdk/jre/lib when
// integrated with jdk.
// else it should be picked from -D option from command line.
// -Drowset.properties will add to standard properties. Similar
// keys will over-write
/*
* Dependent on application
*/
if (strRowsetProperties != null) {
// Load user's implementation of SyncProvider
// here. -Drowset.properties=/abc/def/pqr.txt
}
}
/*
* Always available
*/
try (InputStream stream =
throw new SyncFactoryException(
}
}
// removed else, has properties should sum together
} catch (FileNotFoundException e) {
throw new SyncFactoryException("Cannot locate properties file: " + e);
} catch (IOException e) {
throw new SyncFactoryException("IOException: " + e);
}
/*
* Now deal with -Drowset.provider.classname
* load additional properties from -D command line
*/
properties.clear();
if (providerImpls != null) {
int i = 0;
while (tokenizer.hasMoreElements()) {
i++;
}
} else {
}
}
}
}
/**
* The internal debug switch.
*/
private static boolean debug = false;
/**
* Internal registry count for the number of providers contained in the
* registry.
*/
/**
* Internal handler for all standard property parsing. Parses standard
* ROWSET properties and stores lazy references into the the internal registry.
*/
impl = new ProviderImpl();
// no property index has been set.
propertyNames = getPropertyNames(false);
} else {
// property index has been set.
}
}
}
}
/**
* Used by the parseProperties methods to disassemble each property tuple.
*/
}
/**
* Disassembles each property and its associated value. Also handles
* overloaded property names that contain indexes.
*/
String[] propertyNames =
if (append) {
propertyNames[i] = propertyNames[i] +
dot +
}
return propertyNames;
} else {
return propertyNames;
}
}
/**
* Internal debug method that outputs the registry contents.
*/
}
/**
* Returns the <code>SyncProvider</code> instance identified by <i>providerID</i>.
*
* @param providerID the unique identifier of the provider
* @return a <code>SyncProvider</code> implementation
* @throws SyncFactoryException If the SyncProvider cannot be found,
* the providerID is {@code null}, or
* some error was encountered when trying to invoke this provider.
*/
throws SyncFactoryException {
if(providerID == null) {
throw new SyncFactoryException("The providerID cannot be null");
}
initMapIfNecessary(); // populate HashTable
initJNDIContext(); // check JNDI context for any additional bindings
// Requested SyncProvider is unavailable. Return default provider.
}
// Attempt to invoke classname from registered SyncProvider list
try {
/**
* The SyncProvider implementation of the user will be in
* the classpath. We need to find the ClassLoader which loads
* this SyncFactory and try to laod the SyncProvider class from
* there.
**/
if (c != null) {
return (SyncProvider) c.newInstance();
} else {
}
} catch (IllegalAccessException e) {
} catch (InstantiationException e) {
} catch (ClassNotFoundException e) {
}
}
/**
* Returns an Enumeration of currently registered synchronization
* providers. A <code>RowSet</code> implementation may use any provider in
* the enumeration as its <code>SyncProvider</code> object.
* <p>
* At a minimum, the reference synchronization provider allowing
* RowSet content data to be stored using a JDBC driver should be
* possible.
*
* @return Enumeration A enumeration of available synchronization
* providers that are registered with this Factory
*/
throws SyncFactoryException {
// return a collection of classnames
// of type SyncProvider
return implementations.elements();
}
/**
* Sets the logging object to be used by the <code>SyncProvider</code>
* implementation provided by the <code>SyncFactory</code>. All
* <code>SyncProvider</code> implementations can log their events to
* this object and the application can retrieve a handle to this
* object using the <code>getLogger</code> method.
* <p>
* This method checks to see that there is an {@code SQLPermission}
* object which grants the permission {@code setSyncFactory}
* before allowing the method to succeed. If a
* {@code SecurityManager} exists and its
* {@code checkPermission} method denies calling {@code setLogger},
* this method throws a
* {@code java.lang.SecurityException}.
*
* @param logger A Logger object instance
* @throws java.lang.SecurityException if a security manager exists and its
* {@code checkPermission} method denies calling {@code setLogger}
* @throws NullPointerException if the logger is null
* @see SecurityManager#checkPermission
*/
}
throw new NullPointerException("You must provide a Logger");
}
}
/**
* Sets the logging object that is used by <code>SyncProvider</code>
* implementations provided by the <code>SyncFactory</code> SPI. All
* <code>SyncProvider</code> implementations can log their events
* to this object and the application can retrieve a handle to this
* object using the <code>getLogger</code> method.
* <p>
* This method checks to see that there is an {@code SQLPermission}
* object which grants the permission {@code setSyncFactory}
* before allowing the method to succeed. If a
* {@code SecurityManager} exists and its
* {@code checkPermission} method denies calling {@code setLogger},
* this method throws a
* {@code java.lang.SecurityException}.
*
* @param logger a Logger object instance
* @param level a Level object instance indicating the degree of logging
* required
* @throws java.lang.SecurityException if a security manager exists and its
* {@code checkPermission} method denies calling {@code setLogger}
* @throws java.util.logging.LoggingPermission if a security manager exists and its
* {@code checkPermission} method denies calling {@code setLevel}
* @throws NullPointerException if the logger is null
* @see SecurityManager#checkPermission
* @see LoggingPermission
*/
// singleton
}
throw new NullPointerException("You must provide a Logger");
}
}
/**
* Returns the logging object for applications to retrieve
* synchronization events posted by SyncProvider implementations.
*
* @throws SyncFactoryException if no logging object has been set.
*/
// only one logger per session
throw new SyncFactoryException("(SyncFactory) : No logger has been set");
}
return result;
}
/**
* Sets the initial JNDI context from which SyncProvider implementations
* can be retrieved from a JNDI namespace
* <p>
* This method checks to see that there is an {@code SQLPermission}
* object which grants the permission {@code setSyncFactory}
* before allowing the method to succeed. If a
* {@code SecurityManager} exists and its
* {@code checkPermission} method denies calling {@code setJNDIContext},
* this method throws a
* {@code java.lang.SecurityException}.
*
* @param ctx a valid JNDI context
* @throws SyncFactoryException if the supplied JNDI context is null
* @throws java.lang.SecurityException if a security manager exists and its
* {@code checkPermission} method denies calling {@code setJNDIContext}
* @see SecurityManager#checkPermission
*/
throws SyncFactoryException {
}
throw new SyncFactoryException("Invalid JNDI context supplied");
}
}
/**
* Controls JNDI context initialization.
*
* @throws SyncFactoryException if an error occurs parsing the JNDI context
*/
try {
lazyJNDICtxRefresh = true; // touch JNDI namespace once.
} catch (NamingException e) {
e.printStackTrace();
} catch (Exception e) {
e.printStackTrace();
}
}
}
/**
* Internal switch indicating whether the JNDI namespace should be re-read.
*/
private static boolean lazyJNDICtxRefresh = false;
/**
* Parses the set JNDI Context and passes bindings to the enumerateBindings
* method when complete.
*/
// Hunt one level below context for available SyncProvider objects
return properties;
}
/**
* Scans each binding on JNDI context and determines if any binding is an
* instance of SyncProvider, if so, add this to the registry and continue to
* scan the current context using a re-entrant call to this method until all
* bindings have been enumerated.
*/
boolean syncProviderObj = false; // move to parameters ?
try {
// skip directories/sub-contexts
syncProviderObj = true;
}
}
if (syncProviderObj) {
sync.getProviderID());
syncProviderObj = false; // reset
}
}
// Re-entrant call into method
}
}
/**
* Lazy initialization Holder class used by {@code getSyncFactory}
*/
private static class SyncFactoryHolder {
}
}
/**
* Internal class that defines the lazy reference construct for each registered
* SyncProvider implementation.
*/
private int index;
}
return className;
}
vendorName = vendor;
}
return vendorName;
}
ver = providerVer;
}
return ver;
}
public void setIndex(int i) {
index = i;
}
public int getIndex() {
return index;
}
int dsLock = 0;
try {
} catch (SyncFactoryException sfEx) {
}
return dsLock;
}
public int getProviderGrade() {
int grade = 0;
try {
} catch (SyncFactoryException sfEx) {
//
}
return grade;
}
return className;
}
/*
public javax.sql.RowSetInternal getRowSetInternal() {
try
{
return SyncFactory.getInstance(className).getRowSetInternal();
} catch(SyncFactoryException sfEx) {
//
}
}
*/
try {
} catch (SyncFactoryException sfEx) {
//
}
return rsReader;
}
try {
} catch (SyncFactoryException sfEx) {
//
}
return rsWriter;
}
throws SyncProviderException {
try {
} catch (SyncFactoryException sfEx) {
}
}
public int supportsUpdatableView() {
int view = 0;
try {
} catch (SyncFactoryException sfEx) {
//
}
return view;
}
}