com.ibm.broker.config.proxy

Class BarFile

  • java.lang.Object
    • com.ibm.broker.config.proxy.BarFile


  • public class BarFile
    extends java.lang.Object

    Represents a broker archive file on the local filesystem.

    After deployment, each deployed artefact contains a property that is the name of the BarFile in which it was successfully deployed. However, to retrieve the complete contents of that BarFile, it must exist on the local filesystem. In other words, once a BarFile is deployed it cannot be retrieved from the broker.

    To instantiate BarFile objects, you must use a BarFile factory method. If you modify the BarFile in any way, you must use one of either the save() or saveAs() methods in order to make the changes persistent. For example:

         BarFile b = BarFile.loadBarFile("C:\\MyBars\\test.bar");
         DeploymentDescriptor d = new DeploymentDescriptor();
         // ...
         b.setDeploymentDescriptor(d);
         b.save();
     

    com.ibm.broker.config.proxy.BarFile

    Responsibilities A representation of a broker archive file on the local filesystem. Provides the ability to list the contents and manipulate the deployment descriptor
    Internal Collaborators com.ibm.broker.config.proxy.DeploymentDescriptor
    
     Change Activity:
     -------- ----------- -------------   ------------------------------------
     Reason:  Date:       Originator:     Comments:
     -------- ----------- -------------   ------------------------------------
     45166    2007-06-05  HDMPL           v6.1 Release
     51619.3  2008-08-26  HDMPL           v7 Release:
                                            Added getFullName()
                                            Added isValid()
     80006    2011-05-13  HDCAB           v8 release:                                        
                                             Added equals() method.
                                             Added loadBarFile(byte[], String)
                                             Added applyOverrides() methods
                                             Added toString() method
     
     
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method and Description
      java.util.Enumeration<LogEntry> applyOverrides(BarFile sourceBarFile, java.lang.String applicationName, java.lang.String libraryName, boolean recursive)
      Copies the deployment descriptor(s) from the source BAR file to this BAR file.
      java.util.Enumeration<LogEntry> applyOverrides(DeploymentDescriptor newDeploymentDescriptor, java.lang.String applicationName, java.lang.String libraryName, boolean recursive)
      Replaces the existing deployment descriptor(s) with a new deployment descriptor.
      java.util.Enumeration<LogEntry> applyOverrides(java.util.HashMap<java.lang.String,java.lang.String> overrides, java.lang.String applicationName, java.lang.String libraryName, boolean recursive)
      Updates the deployment descriptor(s) with the specified overrides.
      boolean equals(java.lang.Object obj)
      Compares this BarFile with the Object passed in.
      java.util.Enumeration<BarEntry> getBarEntries()
      Returns the set of Bar entries that are contained in the BarFile.
      BarEntry getBarEntryByName(java.lang.String filename)
      Returns the bar entry that has the supplied filename.
      java.util.Enumeration<java.lang.String> getBarEntryNames()
      Returns the set of Bar entry filenames that are contained in the BarFile.
      DeploymentDescriptor getDeploymentDescriptor()
      Returns the object that represents the deployment descriptor.
      java.lang.String getFullName()
      Returns the full path and file name of the BarFile, as supplied to the loadBarFile method.
      static boolean isValid(byte[] barData)
      Performs a cursory check of the file with the supplied contents and returns true if it appears to be a Bar file in a valid format.
      static boolean isValid(java.lang.String pathAndFileName)
      Performs a cursory check of the file pointed to by the supplied argument and returns true if it appears to be a Bar file in a valid format.
      static BarFile loadBarFile(byte[] barFileContents, java.lang.String fileName)
      Factory for the BarFile class.
      static BarFile loadBarFile(java.lang.String pathAndFileName)
      Factory for the BarFile class.
      void save()
      Saves the contents of the BarFile to a file on the local filesystem.
      void saveAs(java.lang.String outputFilename)
      Saves the contents of the BarFile to a file on the local filesystem.
      void setDeploymentDescriptor(DeploymentDescriptor newDescriptor)
      Sets the deployment descriptor associated with this object.
      void setFullName(java.lang.String fileName)
      Sets the Bar file name.
      java.lang.String toString()
      Returns a string representation of the object
      • Methods inherited from class java.lang.Object

        getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Method Detail

      • loadBarFile

        public static BarFile loadBarFile(java.lang.String pathAndFileName)
                                   throws java.io.IOException
        Factory for the BarFile class. If the File to which the BarFile refers already exists on the local filesystem, its contents are read and stored locally.
        Parameters:
        pathAndFileName - Local path and filename that points to the BarFile to be read or created.
        Throws:
        java.io.IOException - if the file could not be successfully read
      • loadBarFile

        public static BarFile loadBarFile(byte[] barFileContents,
                                          java.lang.String fileName)
                                   throws java.io.IOException
        Factory for the BarFile class. The byte array contains the bytes for the bar file.
        Parameters:
        barFileContents - contents of a bar file as a byte array
        Throws:
        java.io.IOException - if the file could not be successfully read
      • isValid

        public static boolean isValid(java.lang.String pathAndFileName)
                               throws java.io.FileNotFoundException,
                                      java.io.IOException
        Performs a cursory check of the file pointed to by the supplied argument and returns true if it appears to be a Bar file in a valid format. A returned value of true does not guarantee that the Bar file can be successfully deployed. Note that an empty Bar file is considered to be valid.
        Parameters:
        pathAndFileName - Local path and filename that points to the BarFile to be read or created.
        Returns:
        boolean
        Throws:
        java.io.FileNotFoundException - if the file could not be found
        java.io.IOException - if the file could not be read
      • isValid

        public static boolean isValid(byte[] barData)
        Performs a cursory check of the file with the supplied contents and returns true if it appears to be a Bar file in a valid format. A returned value of true does not guarantee that the Bar file can be successfully deployed. Note that an empty Bar file is considered to be valid.
        Parameters:
        barData - byte array representing the contents of the Bar file
        Returns:
        boolean
      • getFullName

        public java.lang.String getFullName()
        Returns the full path and file name of the BarFile, as supplied to the loadBarFile method.
        Returns:
        String name of the BarFile.
      • setFullName

        public void setFullName(java.lang.String fileName)
        Sets the Bar file name.
        Parameters:
        fileName -
      • getDeploymentDescriptor

        public DeploymentDescriptor getDeploymentDescriptor()
        Returns the object that represents the deployment descriptor. If there is no deployment descriptor associated with this BarFile, this method returns null.
        Returns:
        DeploymentDescriptor
      • setDeploymentDescriptor

        public void setDeploymentDescriptor(DeploymentDescriptor newDescriptor)
        Sets the deployment descriptor associated with this object. This method causes a new Bar file to be written to the local filesystem. If the supplied DeploymentDescriptor is null, any active deployment descriptor will be removed.

        If backupDescriptorName is not null, the previous deployment descriptor will be renamed inside the Bar file to the file specified. Any path name will be ignored; the backup file will be placed in the META-INF directory and will replace any file of the same name.

        If backupBarName is not null, the original Bar file will be backed up to the supplied name before the operation begins.

        Parameters:
        newDescriptor - object representing the new deployment descriptor.
      • getBarEntryNames

        public java.util.Enumeration<java.lang.String> getBarEntryNames()
        Returns the set of Bar entry filenames that are contained in the BarFile.
        Returns:
        Enumeration
      • getBarEntries

        public java.util.Enumeration<BarEntry> getBarEntries()
        Returns the set of Bar entries that are contained in the BarFile.
        Returns:
        Enumeration
      • getBarEntryByName

        public BarEntry getBarEntryByName(java.lang.String filename)
        Returns the bar entry that has the supplied filename. The format of the filename is the same as was supplied by getBarEntryName(). If no BarEntry exists with the supplied name, null is returned.
        Parameters:
        filename - Full path name of the BarEntry
        Returns:
        BarEntry
      • save

        public void save()
                  throws java.io.IOException
        Saves the contents of the BarFile to a file on the local filesystem. If any changes have been made to the deployment descriptor since it was instantiated, this method causes these changes to be persisted. The original Bar file is replaced with the new one.
        Throws:
        java.io.IOException - if either the contents of the old Bar file could not be read or the new file could not be written.
      • saveAs

        public void saveAs(java.lang.String outputFilename)
                    throws java.io.IOException
        Saves the contents of the BarFile to a file on the local filesystem. If any changes have been made to the deployment descriptor since it was instantiated, this method causes these changes to be persisted.
        Parameters:
        outputFilename - Name of the filename to use to save the Bar file.
        Throws:
        java.io.IOException - if either the contents of the old Bar file could not be read or the new file could not be written.
      • applyOverrides

        public java.util.Enumeration<LogEntry> applyOverrides(java.util.HashMap<java.lang.String,java.lang.String> overrides,
                                                              java.lang.String applicationName,
                                                              java.lang.String libraryName,
                                                              boolean recursive)
                                                       throws java.io.IOException
        Updates the deployment descriptor(s) with the specified overrides.

        This method will apply the overrides key-value pairs to the deployment descriptor(s) based on the application name, library name and recursive parameter.

        Parameters:
        overrides - the overrides to apply. If the overrides object is null or empty then no overrides are applied. If the key for an entry is a configurable property URI then the new value will be used as the override unless the value is null. If the value is null then the configurable property override will be removed. If the key for an entry contains an old configurable property value then all configurable properties with this old value will have the new value applied irrespective of the URI.
        applicationName - identifies a specific application in the BAR file to which to apply the overrides. If the application name is null then all applications will be updated.
        libraryName - identifies a specific library (either within the BAR file or parent application) to which to apply the overrides. If the library name is null then all libraries will be updated within the identified parent.
        recursive - Indicates whether to recurse through any nested application/libraries
        Returns:
        Enumeration of LogEntries reporting outcome of applying the overrides.
        Throws:
        java.io.IOException - if any Application or Library file could not be read.
      • applyOverrides

        public java.util.Enumeration<LogEntry> applyOverrides(DeploymentDescriptor newDeploymentDescriptor,
                                                              java.lang.String applicationName,
                                                              java.lang.String libraryName,
                                                              boolean recursive)
                                                       throws java.io.IOException
        Replaces the existing deployment descriptor(s) with a new deployment descriptor.
        Parameters:
        newDeploymentDescriptor - the new deployment descriptor to apply
        applicationName - identifies a specific application in the BAR file to which to apply the new deployment descriptor. If the application name is null then all applications will be updated.
        libraryName - identifies a specific library (either within the BAR file or parent application) to which to apply the new deployment descriptor. If the library name is null then all libraries will be updated within the identified parent.
        recursive - indicates whether to recurse through any nested application/libraries
        Returns:
        Enumeration of LogEntries reporting outcome of applying the overrides
        Throws:
        java.io.IOException - if any Application or Library file could not be read.
      • applyOverrides

        public java.util.Enumeration<LogEntry> applyOverrides(BarFile sourceBarFile,
                                                              java.lang.String applicationName,
                                                              java.lang.String libraryName,
                                                              boolean recursive)
                                                       throws java.io.IOException
        Copies the deployment descriptor(s) from the source BAR file to this BAR file.

        This method will copy the deployment descriptor(s) from the named BAR file to this BAR file based on the application name, library name and recursive parameter.

        Parameters:
        sourceBarFile - contains the deployment descriptor(s) to copy.
        applicationName - identifies a specific application in the BAR file from which to copy the deployment descriptor(s). If the application name is null then all application deployment descriptor(s) will be considered for copying. The deployment descriptor(s) within an application will only be copied if the application exists in this BAR file.
        libraryName - identifies a specific library (either within the BAR file or parent application) from which to copy the deployment descriptor(s). If the library name is null then all library deployment descriptor(s) will be considered for copying. The deployment descriptor(s) within a library will only be copied if the library exists in this BAR file.
        recursive - Indicates whether to recurse through any nested application/libraries
        Returns:
        Enumeration of LogEntries reporting outcome of applying the overrides.
        Throws:
        java.io.IOException - if any Application or Library file could not be read.
      • equals

        public boolean equals(java.lang.Object obj)
        Compares this BarFile with the Object passed in.

        Two instances of a BarFile are equal if and only if they are both BarFiles and they have the same full name, bar entries and deployment descriptor.

        Overrides:
        equals in class java.lang.Object
        Parameters:
        obj - - the object that is to be compared with this one.
        Returns:
        true if the two BarFile objects are equal
      • toString

        public java.lang.String toString()
        Returns a string representation of the object

        Displays the name, number of BAR entries and deployment descriptor of the current object. The format is not guaranteed, and therefore should not be parsed programatically.

        Overrides:
        toString in class java.lang.Object
        Returns:
        String Representation of the current object