docs: static Class<?>[] sortExceptions(Class<?>[] exceptions,
                                       boolean removeSubclasses)
      {
          int numExceptions = exceptions.length;
          ArrayList<Class<?>> checkedExceptions = new ArrayList<Class<?>>(numExceptions);
  
          // -----------------------------------------------------------------------
          // Assume all passed exception are valid application exception, but they
          // cannot just be added to the end of the list, since they may be a
          // subclass of other exceptions on the throws clause, which could result
          // in 'unreachable' code when adding 'catch' blocks.
          //
          // Instead, do one of two things:
          // 1 - Remove any exceptions that are subclasses of other exceptions.
          //     This is useful when a catch block is being added for each
          //     checked exception, and the processing done in the parent
          //     exception would be the same as any subclasses.  For example,
          //     in a generated wrapper, catch blocks for all checked exceptions
          //     just call 'setCheckedException'... so no need to duplicate that
          //     for all subclass exceptions.
          // 2 - Insert the current exception ahead of the first exception
          //     already in the list that is a parent.  This eliminates the
          //     'unreachable' code problem, and also ends up with the
          //     exceptions in the original order if there are no subclasses.
          // -----------------------------------------------------------------------
          for (Class<?> exception : exceptions)
          {
              if (removeSubclasses)
              {
                  // -----------------------------------------------------------------
                  // Remove any exceptions that are subclasses of others
                  // -----------------------------------------------------------------
                  boolean isSubclass = false;
                  for (Class<?> parentEx : exceptions)
                  {
                      if ((exception != parentEx) &&
                          (parentEx.isAssignableFrom(exception)))
                      {
                          if (TraceComponent.isAnyTracingEnabled() && tc.isDebugEnabled())
                              Tr.debug(tc, "getCheckedExceptions: ignoring " +
                                           exception.getName() + ", subclass of " +
                                           parentEx.getName());
                          isSubclass = true;
                          break;
                      }
                  }
  
                  if (!isSubclass)
                      checkedExceptions.add(exception);
              }
              else
              {
                  // -----------------------------------------------------------------
                  // Sort exceptions, so that subclasses are ahead of parents
                  // -----------------------------------------------------------------
                  int j;
                  int numChecked = checkedExceptions.size();
                  for (j = 0; j < numChecked; ++j)
                  {
                      Class<?> checkedEx = checkedExceptions.get(j);
                      if (checkedEx.isAssignableFrom(exception))
                          break;
                  }
  
                  checkedExceptions.add(j, exception);
              }
          }
  
          return checkedExceptions.toArray(new Class[checkedExceptions.size()]);
      }