com.helger.commons.state.ESuccess Java Examples

/**
 * Write a Micro Node to an {@link OutputStream}.
 *
 * @param aNode
 *        The node to be serialized. May be any kind of node (incl.
 *        documents). May not be <code>null</code>.
 * @param aOS
 *        The output stream to write to. May not be <code>null</code>. The
 *        output stream is closed anyway directly after the operation finishes
 *        (on success and on error).
 * @param aSettings
 *        The settings to be used for the creation. May not be
 *        <code>null</code>.
 * @return {@link ESuccess}
 */
@Nonnull
public static ESuccess writeToStream (@Nonnull final IMicroNode aNode,
                                      @Nonnull @WillClose final OutputStream aOS,
                                      @Nonnull final IXMLWriterSettings aSettings)
{
  ValueEnforcer.notNull (aNode, "Node");
  ValueEnforcer.notNull (aOS, "OutputStream");
  ValueEnforcer.notNull (aSettings, "Settings");

  try
  {
    final MicroSerializer aSerializer = new MicroSerializer (aSettings);
    aSerializer.write (aNode, aOS);
    return ESuccess.SUCCESS;
  }
  finally
  {
    StreamHelper.close (aOS);
  }
}
 

@Nonnull
public final ESuccess stopQueuingNewObjects ()
{
  return m_aRWLock.writeLockedGet ( () -> {
    try
    {
      // put specific stop queue object
      m_aQueue.put (STOP_QUEUE_OBJECT);
      m_bStopTakingNewObjects = true;
      return ESuccess.SUCCESS;
    }
    catch (final InterruptedException ex)
    {
      LOGGER.error ("Error stopping queue", ex);
      Thread.currentThread ().interrupt ();
      return ESuccess.FAILURE;
    }
  });
}
 

@Nonnull
public final ESuccess changeParent (@Nonnull final ITEMTYPE aNewParent)
{
  ValueEnforcer.notNull (aNewParent, "NewParent");

  // no change so far
  if (getParent () == aNewParent)
    return ESuccess.SUCCESS;

  // cannot make a child of this, this' new parent.
  final ITEMTYPE aThis = thisAsT ();
  if (aNewParent.isSameOrChildOf (aThis))
    return ESuccess.FAILURE;

  // add this to the new parent
  if (getParent ().removeChild (aThis).isUnchanged ())
    throw new IllegalStateException ("Failed to remove this from parent!");

  // Remember new parent!
  m_aParent = aNewParent;
  return ESuccess.valueOfChange (aNewParent.internalAddChild (aThis));
}
 

/**
 * Write a CSS 3.0 declaration to a file using UTF-8 encoding.
 *
 * @param aCSS
 *        The CSS to be written to a file. May not be <code>null</code>.
 * @param aFile
 *        The file to be written. May not be <code>null</code>.
 * @return {@link ESuccess#SUCCESS} if everything went okay, and
 *         {@link ESuccess#FAILURE} if an error occurred
 */
public ESuccess writeCSS30 (final CascadingStyleSheet aCSS, final File aFile)
{
  // 1.param: version to write
  // 2.param: false== non-optimized output
  final CSSWriterSettings aSettings = new CSSWriterSettings (ECSSVersion.CSS30, false);
  try
  {
    final CSSWriter aWriter = new CSSWriter (aSettings);
    // Write the @charset rule: (optional)
    aWriter.setContentCharset (StandardCharsets.UTF_8.name ());
    // Write a nice file header
    aWriter.setHeaderText ("This file was generated by ph-css\nGrab a copy at https://github.com/phax/ph-css");
    // Convert the CSS to a String
    final String sCSSCode = aWriter.getCSSAsString (aCSS);
    // Finally write the String to a file
    return SimpleFileIO.writeFile (aFile, sCSSCode, StandardCharsets.UTF_8);
  }
  catch (final Exception ex)
  {
    LOGGER.error ("Failed to write the CSS to a file", ex);
    return ESuccess.FAILURE;
  }
}
 

@Nonnull
public final ESuccess queueObject (@Nonnull final DATATYPE aObject)
{
  ValueEnforcer.notNull (aObject, "Object");
  if (isStopped ())
    throw new IllegalStateException ("The queue is already stopped and does not take any more elements");

  return m_aRWLock.writeLockedGet ( () -> {
    try
    {
      m_aQueue.put (aObject);
      return ESuccess.SUCCESS;
    }
    catch (final InterruptedException ex)
    {
      LOGGER.error ("Failed to submit object to queue", ex);
      Thread.currentThread ().interrupt ();
      return ESuccess.FAILURE;
    }
  });
}
 

/**
 * Close the passed object, without trying to call flush on it.
 *
 * @param aCloseable
 *        The object to be closed. May be <code>null</code>.
 * @return {@link ESuccess#SUCCESS} if the object was successfully closed.
 */
@Nonnull
public static ESuccess closeWithoutFlush (@Nullable @WillClose final AutoCloseable aCloseable)
{
  if (aCloseable != null)
  {
    try
    {
      // close stream
      aCloseable.close ();
      return ESuccess.SUCCESS;
    }
    catch (final Exception ex)
    {
      if (!isKnownEOFException (ex))
        LOGGER.error ("Failed to close object " + aCloseable.getClass ().getName (), _propagate (ex));
    }
  }
  return ESuccess.FAILURE;
}
 

@Nonnull
public final ESuccess write (@Nonnull final JAXBTYPE aObject,
                             @Nonnull final IJAXBMarshaller <JAXBTYPE> aMarshallerFunc)
{
  ValueEnforcer.notNull (aObject, "Object");
  ValueEnforcer.notNull (aMarshallerFunc, "MarshallerFunc");

  try
  {
    final Marshaller aMarshaller = _createMarshaller (getClassLoader ());
    customizeMarshaller (aMarshaller);

    final JAXBElement <JAXBTYPE> aJAXBElement = m_aJAXBElementWrapper.apply (aObject);
    aMarshallerFunc.doMarshal (aMarshaller, aJAXBElement);
    return ESuccess.SUCCESS;
  }
  catch (final JAXBException ex)
  {
    m_aWriteExceptionCallbacks.forEach (x -> x.onException (ex));
  }
  return ESuccess.FAILURE;
}
 

/**
 * Write the passed object to a {@link Writer}.
 *
 * @param aObject
 *        The object to be written. May not be <code>null</code>.
 * @param aWriter
 *        The writer to write to. Will always be closed. May not be
 *        <code>null</code>.
 * @return {@link ESuccess}
 */
@Nonnull
default ESuccess write (@Nonnull final JAXBTYPE aObject, @Nonnull @WillClose final Writer aWriter)
{
  try
  {
    if (USE_JAXB_CHARSET_FIX)
    {
      return write (aObject, SafeXMLStreamWriter.create (aWriter, getXMLWriterSettings ()));
    }
    return write (aObject, TransformResultFactory.create (aWriter));
  }
  finally
  {
    // Needs to be manually closed
    StreamHelper.close (aWriter);
  }
}
 

@Nonnull
public ESuccess returnObject (@Nonnull final DATATYPE aItem)
{
  m_aLock.lock ();
  try
  {
    for (int i = 0; i < m_aItems.length; ++i)
      if (m_aUsed[i] && aItem == m_aItems[i])
      {
        m_aUsed[i] = false;

        // Okay, we have one more unused item
        m_aAvailable.release ();
        return ESuccess.SUCCESS;
      }
    if (!isSilentMode ())
      LOGGER.warn ("Object " + aItem + " is not pooled!");
    return ESuccess.FAILURE;
  }
  finally
  {
    m_aLock.unlock ();
  }
}
 

@Nonnull
public static ESuccess release (@Nullable final FileLock aFileLock)
{
  if (aFileLock != null)
  {
    try
    {
      aFileLock.release ();
      return ESuccess.SUCCESS;
    }
    catch (final IOException ex)
    {
      if (LOGGER.isErrorEnabled ())
        LOGGER.error ("Failed to release object " + aFileLock, ex instanceof IMockException ? null : ex);
    }
  }

  return ESuccess.FAILURE;
}
 

/**
 * Write bytes to an {@link OutputStream}.
 *
 * @param aOS
 *        The output stream to write to. May not be <code>null</code>. Is
 *        closed independent of error or success.
 * @param aBuf
 *        The byte array from which is to be written. May not be
 *        <code>null</code>.
 * @param nOfs
 *        The 0-based index to the first byte in the array to be written. May
 *        not be &lt; 0.
 * @param nLen
 *        The non-negative amount of bytes to be written. May not be &lt; 0.
 * @return {@link ESuccess}
 */
@Nonnull
public static ESuccess writeStream (@WillClose @Nonnull final OutputStream aOS,
                                    @Nonnull final byte [] aBuf,
                                    @Nonnegative final int nOfs,
                                    @Nonnegative final int nLen)
{
  try
  {
    ValueEnforcer.notNull (aOS, "OutputStream");
    ValueEnforcer.isArrayOfsLen (aBuf, nOfs, nLen);

    aOS.write (aBuf, nOfs, nLen);
    aOS.flush ();
    return ESuccess.SUCCESS;
  }
  catch (final IOException ex)
  {
    LOGGER.error ("Failed to write to output stream", _propagate (ex));
    return ESuccess.FAILURE;
  }
  finally
  {
    close (aOS);
  }
}
 

/**
 * Write the passed collection to the passed output stream using the
 * predefined XML layout.
 *
 * @param aCollection
 *        The map to be written. May not be <code>null</code>.
 * @param aOS
 *        The output stream to write to. The stream is closed independent of
 *        success or failure. May not be <code>null</code>.
 * @return {@link ESuccess#SUCCESS} when everything went well,
 *         {@link ESuccess#FAILURE} otherwise.
 */
@Nonnull
public static ESuccess writeList (@Nonnull final Collection <String> aCollection,
                                  @Nonnull @WillClose final OutputStream aOS)
{
  ValueEnforcer.notNull (aCollection, "Collection");
  ValueEnforcer.notNull (aOS, "OutputStream");

  try
  {
    final IMicroDocument aDoc = createListDocument (aCollection);
    return MicroWriter.writeToStream (aDoc, aOS, XMLWriterSettings.DEFAULT_XML_SETTINGS);
  }
  finally
  {
    StreamHelper.close (aOS);
  }
}
 

/**
 * Read a mapping from the passed input stream.
 *
 * @param aIS
 *        The input stream to read from. May not be <code>null</code>.
 * @param aTargetMap
 *        The target map to be filled.
 * @return {@link ESuccess#SUCCESS} if the stream could be opened, if it could
 *         be read as XML and if the root element was correct.
 *         {@link ESuccess#FAILURE} otherwise.
 */
@Nonnull
public static ESuccess readMap (@Nonnull @WillClose final InputStream aIS,
                                @Nonnull final Map <String, String> aTargetMap)
{
  ValueEnforcer.notNull (aIS, "InputStream");
  ValueEnforcer.notNull (aTargetMap, "TargetMap");

  try (final InputStream aCloseMe = aIS)
  {
    // open file
    final IMicroDocument aDoc = MicroReader.readMicroXML (aIS);
    if (aDoc != null)
    {
      readMap (aDoc.getDocumentElement (), aTargetMap);
      return ESuccess.SUCCESS;
    }
  }
  catch (final Exception ex)
  {
    if (LOGGER.isWarnEnabled ())
      LOGGER.warn ("Failed to read mapping resource '" + aIS + "'", ex);
  }
  return ESuccess.FAILURE;
}
 

/**
 * Write a Micro Node to a {@link Writer}.
 *
 * @param aNode
 *        The node to be serialized. May be any kind of node (incl.
 *        documents). May not be <code>null</code>.
 * @param aWriter
 *        The writer to write to. May not be <code>null</code>. The writer is
 *        closed anyway directly after the operation finishes (on success and
 *        on error).
 * @param aSettings
 *        The settings to be used for the creation. May not be
 *        <code>null</code>.
 * @return {@link ESuccess}
 */
@Nonnull
public static ESuccess writeToWriter (@Nonnull final IMicroNode aNode,
                                      @Nonnull @WillClose final Writer aWriter,
                                      @Nonnull final IXMLWriterSettings aSettings)
{
  ValueEnforcer.notNull (aNode, "Node");
  ValueEnforcer.notNull (aWriter, "Writer");
  ValueEnforcer.notNull (aSettings, "Settings");

  try
  {
    final MicroSerializer aSerializer = new MicroSerializer (aSettings);
    aSerializer.write (aNode, aWriter);
    return ESuccess.SUCCESS;
  }
  finally
  {
    StreamHelper.close (aWriter);
  }
}
 

@Nonnull
public static ESuccess writeList (@Nonnull final Collection <String> aCollection,
                                  @Nonnull final IHasOutputStream aOSP)
{
  ValueEnforcer.notNull (aOSP, "OutputStreamProvider");

  return writeList (aCollection, aOSP.getOutputStream (EAppend.DEFAULT));
}
 

/**
 * Pass the content of the given reader to the given writer. The reader is
 * automatically closed, whereas the writer stays open!
 *
 * @param aReader
 *        The reader to read from. May be <code>null</code>. Automatically
 *        closed!
 * @param aWriter
 *        The writer to write to. May be <code>null</code>. Not automatically
 *        closed!
 * @return <code>{@link ESuccess#SUCCESS}</code> if copying took place, <code>
 *         {@link ESuccess#FAILURE}</code> otherwise
 */
@Nonnull
public static ESuccess copyReaderToWriter (@WillClose @Nullable final Reader aReader,
                                           @WillNotClose @Nullable final Writer aWriter)
{
  return copyReaderToWriter (aReader,
                             true,
                             aWriter,
                             false,
                             createDefaultCopyBufferChars (),
                             (Long) null,
                             null,
                             (MutableLong) null);
}
 

/**
 * Pass the content of the given input stream to the given output stream. The
 * input stream is automatically closed, whereas the output stream stays open!
 *
 * @param aIS
 *        The input stream to read from. May be <code>null</code>.
 *        Automatically closed!
 * @param aOS
 *        The output stream to write to. May be <code>null</code>. Not
 *        automatically closed!
 * @return <code>{@link ESuccess#SUCCESS}</code> if copying took place, <code>
 *         {@link ESuccess#FAILURE}</code> otherwise
 */
@Nonnull
public static ESuccess copyInputStreamToOutputStream (@WillClose @Nullable final InputStream aIS,
                                                      @WillNotClose @Nullable final OutputStream aOS)
{
  return copyInputStreamToOutputStream (aIS,
                                        true,
                                        aOS,
                                        false,
                                        createDefaultCopyBufferBytes (),
                                        (Long) null,
                                        null,
                                        (MutableLong) null);
}
 

/**
 * Copy the content of the source file to the destination file using
 * {@link InputStream} and {@link OutputStream}.
 *
 * @param aSrcFile
 *        Source file. May not be <code>null</code>.
 * @param aDestFile
 *        Destination file. May not be <code>null</code>.
 * @return {@link ESuccess}
 */
@Nonnull
private static ESuccess _copyFileViaStreams (@Nonnull final File aSrcFile, @Nonnull final File aDestFile)
{
  final InputStream aSrcIS = FileHelper.getInputStream (aSrcFile);
  if (aSrcIS == null)
    return ESuccess.FAILURE;

  try
  {
    final OutputStream aDstOS = FileHelper.getOutputStream (aDestFile, EAppend.TRUNCATE);
    if (aDstOS == null)
      return ESuccess.FAILURE;

    try
    {
      return StreamHelper.copyInputStreamToOutputStream (aSrcIS, aDstOS);
    }
    finally
    {
      StreamHelper.close (aDstOS);
    }
  }
  finally
  {
    StreamHelper.close (aSrcIS);
  }
}
 

/**
 * Helper function for saving a file with correct error handling.
 *
 * @param sRelativePath
 *        name of the file. May not be <code>null</code>.
 * @param eAppend
 *        Appending mode. May not be <code>null</code>.
 * @param aBytes
 *        the bytes to be written. May not be <code>null</code>.
 * @return {@link ESuccess}
 */
@Nonnull
default ESuccess writeFile (@Nonnull final String sRelativePath,
                            @Nonnull final EAppend eAppend,
                            @Nonnull final byte [] aBytes)
{
  // save to file
  final OutputStream aOS = getOutputStream (sRelativePath, eAppend);
  if (aOS == null)
    return ESuccess.FAILURE;

  // Close the OS automatically!
  return StreamHelper.writeStream (aOS, aBytes);
}
 

@Nonnull
public static ESuccess readList (@Nonnull final IHasInputStream aISP, @Nonnull final Collection <String> aTargetList)
{
  ValueEnforcer.notNull (aISP, "InputStreamProvider");

  return readList (aISP.getInputStream (), aTargetList);
}
 

@Nonnull
public static ESuccess readXMLSAX (@Nonnull final char [] aXML,
                                   @Nonnegative final int nOfs,
                                   @Nonnegative final int nLen,
                                   @Nonnull final ISAXReaderSettings aSettings)
{
  return readXMLSAX (InputSourceFactory.create (aXML, nOfs, nLen), aSettings);
}
 

@Nonnull
public static ESuccess writeMap (@Nonnull final Map <String, String> aMap, @Nonnull final IHasOutputStream aOSP)
{
  ValueEnforcer.notNull (aOSP, "OutputStreamProvider");

  return writeMap (aMap, aOSP.getOutputStream (EAppend.DEFAULT));
}
 

@Nonnull
public static ESuccess readMap (@Nonnull final IMicroElement aParentElement,
                                @Nonnull final Map <String, String> aTargetMap)
{
  ValueEnforcer.notNull (aParentElement, "ParentElement");
  ValueEnforcer.notNull (aTargetMap, "TargetMap");

  try
  {
    // and insert all elements
    for (final IMicroElement eMap : aParentElement.getAllChildElements (ELEMENT_MAP))
    {
      final String sName = eMap.getAttributeValue (ATTR_KEY);
      if (sName == null)
        LOGGER.warn ("Ignoring mapping element because key is null");
      else
      {
        final String sValue = eMap.getAttributeValue (ATTR_VALUE);
        if (sValue == null)
          LOGGER.warn ("Ignoring mapping element because value is null");
        else
        {
          if (aTargetMap.containsKey (sName))
            if (LOGGER.isWarnEnabled ())
              LOGGER.warn ("Key '" + sName + "' is already contained - overwriting!");
          aTargetMap.put (sName, sValue);
        }
      }
    }
    return ESuccess.SUCCESS;
  }
  catch (final Exception ex)
  {
    if (LOGGER.isWarnEnabled ())
      LOGGER.warn ("Failed to read mapping document", ex);
  }
  return ESuccess.FAILURE;
}
 

@Nonnull
public static ESuccess readXMLSAX (@Nonnull @WillClose final InputStream aIS,
                                   @Nonnull final ISAXReaderSettings aSettings)
{
  ValueEnforcer.notNull (aIS, "InputStream");

  try
  {
    return readXMLSAX (InputSourceFactory.create (aIS), aSettings);
  }
  finally
  {
    StreamHelper.close (aIS);
  }
}
 

@Nonnull
public static ESuccess readXMLSAX (@Nonnull @WillClose final Reader aReader,
                                   @Nonnull final ISAXReaderSettings aSettings)
{
  ValueEnforcer.notNull (aReader, "Reader");

  try
  {
    return readXMLSAX (InputSourceFactory.create (aReader), aSettings);
  }
  finally
  {
    StreamHelper.close (aReader);
  }
}
 

/**
 * Internal method to invoke the performed for the passed list of objects.
 *
 * @param aObjectsToPerform
 *        List of objects to be passed to the performer. Never
 *        <code>null</code>. The length is at last
 *        {@link #getMaxPerformCount()}.
 * @return {@link ESuccess}
 */
@Nonnull
private ESuccess _perform (@Nonnull final List <DATATYPE> aObjectsToPerform)
{
  if (!aObjectsToPerform.isEmpty ())
  {
    try
    {
      // Perform the action on the objects, regardless of whether a
      // "stop queue message" was received or not
      m_aPerformer.runAsync (aObjectsToPerform);
    }
    catch (final Exception ex)
    {
      LOGGER.error ("Failed to perform actions on " +
                    aObjectsToPerform.size () +
                    " objects with performer " +
                    m_aPerformer +
                    " - objects are lost!",
                    ex);
      return ESuccess.FAILURE;
    }

    // clear perform-list anyway
    aObjectsToPerform.clear ();
  }

  return ESuccess.SUCCESS;
}
 

/**
 * Pass the content of the given reader to the given writer. The reader and
 * the writer are automatically closed!
 *
 * @param aReader
 *        The reader to read from. May be <code>null</code>. Automatically
 *        closed!
 * @param aWriter
 *        The writer to write to. May be <code>null</code>. Automatically
 *        closed!
 * @return <code>{@link ESuccess#SUCCESS}</code> if copying took place, <code>
 *         {@link ESuccess#FAILURE}</code> otherwise
 */
@Nonnull
public static ESuccess copyReaderToWriterAndCloseWriter (@Nullable @WillClose final Reader aReader,
                                                         @Nullable @WillClose final Writer aWriter)
{
  return copyReaderToWriter (aReader,
                             true,
                             aWriter,
                             true,
                             createDefaultCopyBufferChars (),
                             (Long) null,
                             null,
                             (MutableLong) null);
}
 

@Nonnull
public static ESuccess readMap (@Nonnull final IHasInputStream aISP, @Nonnull final Map <String, String> aTargetMap)
{
  ValueEnforcer.notNull (aISP, "InputStreamProvider");

  return readMap (aISP.getInputStream (), aTargetMap);
}
 

@Nonnull
@MustBeLocked (ELockType.WRITE)
private ESuccess _writeWALFile (@Nonnull @Nonempty final List <DATATYPE> aModifiedElements,
                                @Nonnull final EDAOActionType eActionType,
                                @Nonnull @Nonempty final String sWALFilename)
{
  final FileSystemResource aWALRes = m_aIO.getResource (sWALFilename);
  try (final DataOutputStream aDOS = new DataOutputStream (aWALRes.getOutputStream (EAppend.APPEND)))
  {
    // Write action type ID
    StreamHelper.writeSafeUTF (aDOS, eActionType.getID ());
    // Write number of elements
    aDOS.writeInt (aModifiedElements.size ());
    // Write all data elements as XML Strings :)
    for (final DATATYPE aModifiedElement : aModifiedElements)
    {
      final String sElement = convertNativeToWALString (aModifiedElement);
      StreamHelper.writeSafeUTF (aDOS, sElement);
    }
    return ESuccess.SUCCESS;
  }
  catch (final Exception ex)
  {
    if (LOGGER.isErrorEnabled ())
      LOGGER.error ("Error writing WAL file " + aWALRes, ex);
    triggerExceptionHandlersWrite (ex, sWALFilename, (IMicroDocument) null);
  }
  return ESuccess.FAILURE;
}
 

/**
 * Read a predefined XML file that contains list items.
 *
 * @param aIS
 *        The input stream to read from. May not be <code>null</code>.
 *        Automatically closed no matter whether reading succeeded or not.
 * @param aTargetList
 *        The target collection to be filled. May not be <code>null</code>.
 * @return {@link ESuccess#SUCCESS} if reading succeeded,
 *         {@link ESuccess#FAILURE} if the input stream is no valid XML or any
 *         other error occurred.
 */
@Nonnull
public static ESuccess readList (@Nonnull @WillClose final InputStream aIS,
                                 @Nonnull final Collection <String> aTargetList)
{
  ValueEnforcer.notNull (aIS, "InputStream");
  ValueEnforcer.notNull (aTargetList, "TargetList");

  try
  {
    // open file
    final IMicroDocument aDoc = MicroReader.readMicroXML (aIS,
                                                          new SAXReaderSettings ().setFeatureValues (EXMLParserFeature.AVOID_XXE_SETTINGS));
    if (aDoc != null)
    {
      readList (aDoc.getDocumentElement (), aTargetList);
      return ESuccess.SUCCESS;
    }
  }
  catch (final Exception ex)
  {
    if (LOGGER.isWarnEnabled ())
      LOGGER.warn ("Failed to read list resource '" + aIS + "'", ex);
  }
  finally
  {
    StreamHelper.close (aIS);
  }

  return ESuccess.FAILURE;
}