Package edu.gvsu.kurmasz.warszawa.dl

Class SimpleFactory

java.lang.Object
edu.gvsu.kurmasz.warszawa.dl.SimpleFactory
public class SimpleFactory
extends java.lang.Object
Contains methods for instantiating objects of a class specified at runtime.
Author:
Zachary Kurmas

  • Constructor Details

  • Method Details

    • make

      public static <T> T make​(java.lang.String name, java.lang.Class<T> parentClass, java.lang.Boolean rethrowRuntimeExceptions, java.lang.Object... params) throws DLException
      Instantiate an object of type name and cast the new object to be of type T. This method's main purpose is to instantiate objects that are not known at compile time (e.g., plug-ins). The new object will be cast to some super-type, T. (It can't be cast to its own type, because its own type isn't known at compile time.) Because of Java's type erasure, we need the Class object of T as a parameter to verify that the requested object is actually of type T. (This check is not strictly necessary because if we don't have this Class object, and there is a type mismatch, Java will eventually generate a ClassCastException ; however, we prefer to find any such problems as early as possible.)

      ExampleUsage: 

       PluginInterface plugin = SimpleFactory.make("MyPlugIn", PluginInterface.class);

      The above code assumes that PluginInterface is a Java interface that is known at compile time, and that MyPlugIn is a class that implements the PluginInterface interface.

      Two important limitations:

      • This code does not search for the most specific match among several overload constructors. It will simply throw an exception if more than one constructor could be called given the types of the actual parameters, but no one constructor matches exactly.
      • You cannot directly pass primitive data to the constructor. Any primitive data will be autoboxed. You cannot pass null as a parameter to the constructor.

      Note: It is assumed that the class being dynamically loaded is not in the package edu.gvsu.kurmasz .warszawa.dl. Therefore, it will automatically throw an exception if the user attempts to instantiate class with private or package-protected protection, even though that would normally be allowed for classes in the same package as SimpleFactory. Other "overly aggressive" exceptions may be thrown for similar reasons when attempting to load classes in edu.gvsu.kurmasz.warszawa.dl.

      Normally, when a dynamically invoked constructor throws an exception, a InvocationTargetException is generated with the the exception generated by the constructor as its cause. When rethrowRuntimeExceptions is set to true, any RuntimeExceptions generated by the constructor are simply re-thrown. This allows the calling method to simply check for exceptions as if the object were being created directly (i.e., using new). This feature is limited to RuntimeExceptions only because rethrowing any Exception in general would require this method to include throws Exception in its signature, and we don't want the user to have to explicitly check for a general Exception.

      Type Parameters:
      T - A super-type of the object to be created
      Parameters:
      name - The fully qualified name of the class to be instantiated
      parentClass - The Class object for T (needed to verify that the cast from Object to T is safe).
      rethrowRuntimeExceptions - when true, then this method re-throws any RuntimeExceptions that are the cause of any InvocationTargetException. When false, all InvocationTargetExceptions generate a DLException (the same as any other exception). (See note above).
      params - a list of parameters to the constructor
      Returns:
      an instance of the desired object
      Throws:
      DLException - if anything goes wrong.
      java.lang.IllegalArgumentException - if name or parentClass are null

    • make

      public static <T> T make​(java.lang.String name, java.lang.Class<T> parentClass, java.lang.Object... params) throws DLException
      Calls make(String, Class, Boolean, Object...) with a default value of false for rethrowsRuntimeExceptions
      Type Parameters:
      T - A super-type of the object to be created
      Parameters:
      name - The fully qualified name of the class to be instantiated
      parentClass - The Class object for T (needed to verify that the cast from Object to T is safe).
      params - a list of parameters to the constructor
      Returns:
      an instance of the desired object
      Throws:
      DLException - if anything goes wrong.
      java.lang.IllegalArgumentException - if name or parentClass are null

    • makeOrQuit

      public static <T> T makeOrQuit​(java.lang.String name, java.lang.Class<T> parentClass, java.lang.Boolean rethrowRuntimeExceptions, java.io.PrintStream error, java.lang.Integer exitValue, java.lang.Object... params)
      Try to make(String, Class, Boolean, Object...) a new object, or exit the program if the call to make(String, Class, Boolean, Object...) throws a DLException. (Note: This method only quits when it encounters a DLException. It does not quit if rethrowRuntimeException is true and the constructor throws a RuntimeException.
      Type Parameters:
      T - A super-type of the object to be created
      Parameters:
      name - The fully qualified name of the class to be instantiated
      parentClass - The Class object for T (needed to verify that the cast from Object to T is safe).
      rethrowRuntimeExceptions - when true, then this method re-throws any RuntimeExceptions that are the cause of any InvocationTargetException. When false, all InvocationTargetExceptions generate a DLException (the same as any other exception). (See note above).
      error - the stream to which to print any error messages
      exitValue - the value the process will return on exit
      params - a list of parameters to the constructor
      Returns:
      the newly created object

    • makeOrQuit

      public static <T> T makeOrQuit​(java.lang.String name, java.lang.Class<T> parentClass, java.lang.Boolean rethrowRuntimeExceptions, java.lang.Object... params)
      calls makeOrQuit(String, Class, Boolean, java.io.PrintStream, Integer, Object...) with the default error stream an exit value.

    • makeOrQuit

      public static <T> T makeOrQuit​(java.lang.String name, java.lang.Class<T> parentClass, java.io.PrintStream error, java.lang.Integer exitValue, java.lang.Object... params)
      Calls makeOrQuit(String, Class, Boolean, java.io.PrintStream, Integer, Object...) with default value of false for rethrowRuntimeExceptions

    • makeOrQuit

      public static <T> T makeOrQuit​(java.lang.String name, java.lang.Class<T> parentClass, java.lang.Object... params)
      calls makeOrQuit(String, Class, java.io.PrintStream, Integer, Object...) with the default error stream an exit value.