Sunday, June 5, 2022

Design Pattern: Adapter Pattern

Chapters

Adapter Pattern

Adapter Pattern is a design pattern that makes two incompatible interfaces collaborate. We use adapter if a new codebase that we wanna add to our application is not compatible with our existing interface.

For example, we have an application that lists data in plain text format. Then, we have a third library that process analytics. This library is verified compatible with our application but the problem is that this library returns data in XML format. To resolve this problem, we can look for another library. However, even we find another library we need to verify if it's compatible with our application, which takes time.

Another solution is to modify the library itself. However, a lot of problems may arise. One of them is licensing issue, some libraries are protected by license and thus we can't just modify libraries. Another solution is to create an adapter which is a good solution to this problem.

There are two types of adapter pattern: Object adapter pattern and Class adapter pattern. Object adapter pattern implements the target(interface where another interface is gonna be converted) interface by delegating to an adaptee(interface that is gonna be converted to) object at run-time.

Class adapter pattern implements the target interface by inheriting from an adaptee class at compile-time. This example demonstrates object adapter pattern. 
//client
public class ClientCode{

  public static void main(String[] args){
    PlainTextInterface plainText = 
    new XMLToPlainTextAdapter(new XMLAnalytics());
    
    plainText.displayData();
  }
}

//Assume our third party library has an
//interface
interface XMLInterface{

  String getAnalytics();
}

//Assume this is a third party library
class XMLAnalytics implements XMLInterface{
  private String content;
  
  XMLAnalytics(){
    content= "<data>Testing</data>";
  }
  
  @Override
  public String getAnalytics(){
    return content;
  }
  
}

//Our app's interface
interface PlainTextInterface{

  void displayData();
}

//Our app's class
class PlainTextDisplay implements PlainTextInterface{
  private String data;
  
  PlainTextDisplay(String data){
    this.data = data;
  }
  
  @Override
  public void displayData(){
    System.out.println("Data in plain text: " + data);
  }
}

//Adapter
//In object adapter pattern, we wrap adaptee interface and
//implements target interface
class XMLToPlainTextAdapter implements PlainTextInterface{
  private XMLInterface xml_analytics;
  
  XMLToPlainTextAdapter(XMLInterface xml_analytics){
    this.xml_analytics = xml_analytics;
  }
  
  @Override
  public void displayData(){
    String noTags = 
    xml_analytics.getAnalytics().
    replaceAll("[<][/]??.+?[>]","");
    
    System.out.println("XML converted to plain text");
    System.out.println("Data in plain text: " + noTags);
  }
}

Result
XML converted to plain text
Data in plain text: Testing
Next, let's implement class adapter pattern. First off, change XMLToPlainTextAdapter class to this: 
class XMLToPlainTextAdapter 
      extends XMLAnalytics
      implements PlainTextInterface{
  
  @Override
  public void displayData(){
    String noTags = getAnalytics().
    replaceAll("[<][/]??.+?[>]","");
    
    System.out.println("XML converted to plain text");
    System.out.println("Data in plain text: " + noTags);
  }
}
Then, change ClientCode class to this: 
public class ClientCode{

  public static void main(String[] args){
    PlainTextInterface plainText = 
    new XMLToPlainTextAdapter();
    plainText.displayData();
  }
}
The problem with class adapter pattern is that it doesn't work with all OOP languages. For example, java doesn't support multiple inheritance of classes; this pattern won't work with java if we have multiple adaptees in one adapter.

In the example above, one-way conversion has been implemented to our adapter. However, we can implement two-way conversion which converts XML to plain text and vice-versa.

To do this, we can implement both interfaces in one adapter or create another adapter for conversion from plain text to XML. In my opinion, the latter is more preferrable.
Posted by at No comments:
Labels: ,

Saturday, June 4, 2022

Design Pattern: Prototype Pattern

Chapters

Prototype Pattern

Prototype pattern is a creational design pattern that copies(clone) an object rather than re-creating it. In Object Oriented Programming (OOP), objects are created by instantiating a class.

In java, there's a clone() method that we can use to clone an object rather than re-creating it via instantiation. In this pattern, we create an interface (or abstract class). Then, the client can use the interface to clone its concrete implementations. Take a look at this example. 
import java.util.List;
import java.util.Random;

public class ClientCode{
  
  public static void main(String[] args)
                throws CloneNotSupportedException{
    Prototype protoA = 
    new ConcretePrototypeA("protoA");
    
    System.out.println("Original");
    protoA.displayList();
    System.out.println("\n");
    
    Prototype cloneObj = protoA.clone();
    System.out.println("Clone");
    cloneObj.displayList();
    System.out.println("\n");
    
    System.out.println("Compare Instance");
    System.out.println(
    protoA.compareListInstance(cloneObj.getList()));
  }
}

//factory class
interface Prototype extends Cloneable{
  
  Prototype clone() throws CloneNotSupportedException;
  void displayList();
  boolean compareListInstance(List<Integer> list);
  List<Integer> getList();
}

class ConcretePrototypeA implements Prototype{
  private List<Integer> numbers;
  
  ConcretePrototypeA(String name){
    Random rand = new Random();
    Integer[] values = new Integer[5];
    for(int i = 0; i < values.length; i++)
      values[i] = rand.nextInt(1000);
    numbers = java.util.Arrays.asList(values);
  }
  
  @Override
  public Prototype clone() throws CloneNotSupportedException{
    return (ConcretePrototypeA) super.clone();
  }
  
  public void displayList(){
    numbers.stream().forEach(v -> System.out.print(v + " "));
  }
  
  public boolean compareListInstance(List<Integer> list){
    return list == numbers;
  }
  
  public List<Integer> getList(){
    return numbers;
  }
  
}

Result(may vary)
Original
588 68 607 122 106

Clone
588 68 607 122 106

Compare Instance
true
You can use this pattern when you want to create another Object at runtime that is a true copy of the Object you are cloning. True copy means all the attributes of the newly created Object should be the same as the Object you are cloning.
Posted by at No comments:
Labels: ,

Friday, June 3, 2022

Design Pattern: Builder Pattern

Chapters

Builder Pattern

Builder pattern is a design pattern that separates object creation from objects. It means that we dedicate a class to assemble every parts of an object that we wanna create instead of assembling parts directly in the class of the object. This pattern reduces the complexity of a class. Take a look at this example. 
public class ClientCode{

  public static void main(String[] args){
    House myHouse =
    House.newBuilder("My House").
    installRoof("Gable").
    installWallpaper("Green").
    installTiles("Blue").
    installRooms(3).
    build();
    
    myHouse.houseInfo();
    System.out.println();
    
    myHouse = new 
    Director(
    House.newBuilder("My Another House")).
    construct();
    
    myHouse.houseInfo();
  }
}

class House{
  
  private String houseName;
  private String roof;
  private String wallpaper;
  private String tiles;
  private int rooms;
  private boolean garage;
  
  private House(String houseName){
    this.houseName = houseName;
  }
  
  public static House.HouseBuilder newBuilder(String houseName){
    return new House(houseName).new HouseBuilder();
  }
  
  public void houseInfo(){
    System.out.println("House Name: " + houseName);
    System.out.println("Roof: " + roof);
    System.out.println("Wallpaper: " + wallpaper);
    System.out.println("Tile Color: " + tiles);
    System.out.println("# of Rooms: " + rooms);
    System.out.println("Is there a garage? " + garage);
  }
  
  class HouseBuilder implements Builder{
    
    private HouseBuilder(){
      House.this.roof = "None";
      House.this.wallpaper = "None";
      House.this.tiles = "None";
      House.this.rooms = 0;
      House.this.garage = false;
    }
    
    @Override
    public House.HouseBuilder installRoof(String roof){
      House.this.roof = roof;
      return this;
    }
    
    @Override
    public House.HouseBuilder installWallpaper(String wallpaper){
      House.this.wallpaper = wallpaper;
      return this;
    }
    
    @Override
    public House.HouseBuilder installTiles(String tiles){
      House.this.tiles = tiles;
      return this;
    }
    
    @Override
    public House.HouseBuilder installRooms(int rooms){
      House.this.rooms = rooms;
      return this;
    }
    
    @Override
    public House.HouseBuilder installGarage(boolean install){
      House.this.garage = install;
      return this;
    }
    
    @Override
    public House build(){
      return House.this;
    }
    
  }
}

interface Builder{

  House.HouseBuilder installRoof(String roof);
  House.HouseBuilder installWallpaper(String wallpaper);
  House.HouseBuilder installTiles(String tiles);
  House.HouseBuilder installRooms(int rooms);
  House.HouseBuilder installGarage(boolean install);
  House build();
  
}

class Director{
  private Builder builder; 
  
  public Director(Builder builder){
    this.builder = builder;
  }
  
  public House construct(){
    House houseInstance = null;
    
    if(builder instanceof House.HouseBuilder){
      houseInstance = builder.
      installRoof("Dutch").
      installWallpaper("Blue").
      installRooms(4).
      installGarage(true).
      build();
    }
    return houseInstance;
  }
}

Result
House Name: My House
Roof: Gable
Wallpaper: Green
Tile color: Blue
# of Rooms: 3
Is there a garage? false

House Name: My Another House
Roof: Dutch
Wallpaper: Blue
# of Rooms: 4
Is there a garage? true
You may suggest that there are alternatives to this pattern. Let's assume you're suggesting to use a constructor:

... House(String roof, String wallpaper, String tiles, int rooms, boolean garage)
...

This alternative does make sense in the example above. However, what if want two types of builds of our house? also what if each part of a house in every build has different calculations. In this case, builder pattern is more preferrable. For example, we wanna calculate the size of a roof and each build has different ways of calculating roofs.

In this case, we can just add the calculations to their installRoof methods. Imagine coding two or more types of builds in your House. Your code can become harder to read. Using build pattern, we can encapsulate those builds and their functionalities. Making our House class more clear.

Another advantage of this pattern is that clients can build an object in step-by-step manner. Also, I didn't put any getter or setter methods in the example above but we can put those methods in the House class if we want to.

You might have noticed the Director class. This class contains pre-configured builds of our builders. If you have a build that you often use, you can add that builds in this class, so that you don't need to write your build code everytime you wanna use it. We can also use this class to save client's builds.

In java, some classes implement this pattern. HttpRequest.Builder and DateTimeFormatterBuilder are some examples of classes that implement builder pattern.
Posted by at No comments:
Labels: ,

Wednesday, June 1, 2022

Degin Pattern: Abstract Factory Pattern

Chapters

Abstract Factory Pattern

Abstract factory pattern is just like factory pattern, but this pattern deals with a family of objects and its variants. For example, we are creating classes for two GUI component providers. Both create GUI components but they have different design.

We can use abstract factory method to create a class design in this scenario. Take a look at this example. 
/*
Client
*/
import factories;

public class ClientCode{

  public static void main(String[] args){
    GUIComponentsFactory factory = 
    GUIComponentsFactory.
    selectFactory("Unix");
    Button createdButton = null;
    RadioButton createdRadioButton = null;
    
    if(factory != null){
      createdButton = 
      factory.createButton("MyButton");
      System.out.println
      ("Created Button: " + 
       createdButton.getName());
      System.out.println();
      
      createdRadioButton = 
      factory.createRadioButton("MyRadioButton");
      System.out.println
      ("Created Button: " + 
       createdRadioButton.getName());
    }
  }
}

/*
Factories
Assume classes below are part of factories package
*/

public interface GUIComponentsFactory{
  
  Button createButton(String name);
  RadioButton createRadioButton(String name);
  
  public static GUIComponentsFactory selectFactory(String provider){
    GUIComponentsFactory factory = null;
    
    switch(provider){
    
      case "Windows":
      factory = new CreateWinComponents();
      break;
      
      case "Unix":
      factory = new CreateUnixComponents();
      break;
    }
    return factory;
  }
}

class CreateWinComponents implements GUIComponentsFactory{
  
  CreateWinComponents(){}
  
  @Override
  public Button createButton(String name){
    return new WinButton(name);
  }
  
  @Override
  public RadioButton createRadioButton(String name){
    return new WinRadio(name);
  }
  
}

class CreateUnixComponents implements GUIComponentsFactory{
  
  CreateUnixComponents(){}
  
  @Override
  public Button createButton(String name){
    return new UnixButton(name);
  }
  
  @Override
  public RadioButton createRadioButton(String name){
    return new UnixRadio(name);
  }
}

/*
Objects
*/

pubic abstract class Button{
  private String name;
  
  Button(String name){
    this.name = name;
  }
  
  public String getName(){
    return name;
  }
  
}

class WinButton extends Button{

  WinButton(String name){
    super(name);
    System.out.println(name + 
    " Windows Button has been created!");
  }
}

class UnixButton extends Button{

  UnixButton(String name){
    super(name);
    System.out.println(name + 
    " Unix Button has been created!");
  }
}

public abstract class RadioButton{
  private String name;
  
  RadioButton(String name){
    this.name = name;
  }
  
  public String getName(){
    return name;
  }
  
}

class WinRadio extends RadioButton{

  WinRadio(String name){
    super(name);
    System.out.println(name + 
    " Windows Radio Button has been created!");
  }
}

class UnixRadio extends RadioButton{

  UnixRadio(String name){
    super(name);
    System.out.println(name + 
    " Unix Radio Button has been created!");
  }
}

Result
MyButton Unix Button has been created!
Created Button: MyButton

MyRadioButton Unix Radio Button has been created!
Created Button: MyRadioButton
Just like in factory pattern, factory superclass and objects superclass should be non-instantiable. In short, they can't be instantiated.

One of the advantages of abstract factory pattern over factory pattern is that this pattern implements greater abstraction than factory pattern. However, if you're not producing a family of objects, it's better to use factory pattern.

This pattern inherits the advantages and disadvantages of factory pattern. For more information, you may visit this website
Posted by at No comments:
Labels: ,

Tuesday, May 31, 2022

Design Pattern: Factory Pattern

Chapters

Factory Pattern

Factory Pattern is a design pattern that provides a platform for creating objects in superclass, but sub-classes determine the structure of the created objects. This pattern consists of factory class, factory method, object to be created and classes that extends/implements factory class.

Factory class is a class that contains factory method. Factory method is a method that is overriden by factory subclasses of factory super class. Then overriding methods generate an object that we wanna create such as buttons, etc. This example demonstrates implementation of Factory pattern in java. 
import buttonfactory;

public class ClientCode{

  public static void main(String[] args){
    
    ButtonFactory factory = 
    ButtonFactory.
    selectButtonFactory("Undecorated");
    Button createdButton = null;
    
    if(factory != null){
      createdButton = 
      factory.createButton("MyButton");
      System.out.println
      ("Created Button: " + 
       createdButton.getName());
    }
  }
}

/*
Assume classes below are in buttonfactory package
*/

public interface ButtonFactory{
  
  Button createButton(String name);
  
  static ButtonFactory selectButtonFactory(String name){
    ButtonFactory factory = null;
    switch(name){
    
      case "Standard":
      factory = 
      new CreateStandardButton();
      break;
      
      case "Undecorated":
      factory = 
      new CreateUndecoratedButton();
      break;
    }
    return factory;
  }
}

class CreateStandardButton implements ButtonFactory{
  
  CreateStandardButton(){}
  
  @Override
  public Button createButton(String name){
    return new StandardButton(name);
  }
}

class CreateUndecoratedButton implements ButtonFactory{
  
  CreateUndecoratedButton(){}
  
  @Override
  public Button createButton(String name){
    return new UndecoratedButton(name);
  }
}

public abstract class Button{
  private String name;
  
  public String getName(){
    return name;
  }
  
  Button(String name){
    this.name = name;
  }
  
}

class StandardButton extends Button{
  StandardButton(String name){
    super(name);
    System.out.println(getName() + 
    " standard button has been created!");
  }
}

class UndecoratedButton extends Button{
  UndecoratedButton(String name){
    super(name);
    System.out.println(getName() + 
    " undecorated button has been created!");
  }
}

Result
MyButton undecorated button has been created!
Created Button: MyButton
Typically, factory superclass and objects superclass should be non-instantiable. In short, they can't be instantiated.

One of the advantages of this pattern is that we can add objects, such as new button type, and another factory class subclass without affecting other button types and subclasses of factory class. We can also modify factory sub class and object subclass with little to no effect on other subclasses.

One of the disadvantages of this pattern is that adding more objects or subclasses of factory class can make this pattern complicated real quick.

For more information, you may visit this website.
Posted by at No comments:
Labels: ,

Monday, May 30, 2022

Java Tutorial: Zip4j - A Java library for zip files/streams

Chapters

Introduction

Zip4J is the most comprehensive Java library for zip files or streams. As of this writing, it is the only Java library which has support for zip encryption, apart from several other features. It tries to make handling zip files/streams a lot more easier. No more clunky boiler plate code with input streams and output streams.

Requirements
JDK 7 or later*

* Zip4j is written on JDK 8, as some of the features (NIO) that Zip4j supports requires features available only in JDK 8. However, considering the fact that Zip4j is widely used in Android, and to support older versions of Android, Zip4j supports JDK 7 as well. In cases where the feature/class from JDK 8 is missing, Zip4j falls back to the features available in JDK 7. In other words, when running on JDK 7, not all features will be supported.

zip4j also supports Zip64. Zip64 removes some limitations that ZIP format has. Zip4j will automatically make a zip file with Zip64 format and add appropriate headers, when it detects the zip file to be crossing these limitations. You do not have to explicitly specify any flag for Zip4j to use this feature.

Note: If you're using maven, add this to your pom.xml and you don't need to add a new classpath in order to use zip4j. 
<dependency>
    <groupId>net.lingala.zip4j</groupId>
    <artifactId>zip4j</artifactId>
    <version>2.10.0</version>
</dependency>
</pre>
Latest version can be found here.

Before running the example above, we will temporarily add a new classpath where "src\main\java" folder is located in zip4j folder. Command syntax: 
set classpath=[root]:\[path];
e.g.
set classpath=C:\test\zip4j-2.10.0-master\src\main\java;
Once the new classpath is added, we can execute the example above. Once we close cmd/terminal, number of classpaths in our system will return to normal.

Create a Zip File or Add a File to a Zip File

First off, let's create a zip file and add a single file in it.

View code with code highlight


ZipFile has add*() methods that can be used to create a zip; add a files/folder to a zip file; extract and remove files from zip file. Initializing a ZipFile instance doesn't create a new zip file.

addFile(File fileToAdd) Adds input source file to the zip file with default zip parameters. If zip file does not exist, this method creates a new zip file. This method throws an exception if the file to be added doesn't exist.

ZipParameters Encapsulates the parameters that that control how Zip4J encodes data.

I think closing a ZipFile instance is not necessary because I think the stream that is used by ZipFile is automatically closed. I'm not really sure though that's why I use try-finally clause. Although, in the documentation, the examples there regarding ZipFile don't use try-finally clause.

We can use addFiles(List<File> filesToAdd) to add multiple files to a zip file. This method adds the list of input files to the zip file with default zip parameters. Example: 
import java.util.Arrays;
...
ZipFile zip = null;
...
zip = new ZipFile("myzip.zip");
zip.addFiles(Arrays.asList(
new File("img1.jpg"),
new File("img2.jpg")));
...
This method throws an exception if one of the files in the list doesn't exist. We can use addFolder(File folderToAdd) to add a directory and all of its content to our zip file. This method adds the folder in the given file object to the zip file with default zip parameters. Example: 
...
zip = new ZipFile("myzip.zip");
zip.addFolder(new File("folder1/folderA"));
//valid in windows
//new File("folder1\\folderA");
...
If we want to filter files that can be put in a zip file, we can use setExcludeFileFilter(ExcludeFileFilter excludeFileFilter) method from ZipParameters. Example:

View code with code highlight


In the example above, a file with .JPEG file extension won't be included in the zip file. ZipParameters() creates a ZipParameters instance with default parameters. ExcludeFileFilter is a functional interface.

Create a Zip File or Add a File to a Zip File Using a Stream

If you need to use an input stream to add data to your zip file, you can use addStream(InputStream inputStream, ZipParameters parameters). For example:

View code with code highlight


setFileNameInZip(String fileNameInZip) sets the name of the file where the stream data will be stored. It's required to set the name of the destination file if we're using streams to put data to our zip file. The file extension of the destination file should be equivalent to the intended file extension of the stream data. The path name must be relative and use "/" forward slash as directory separator.

Create a Zip File with STORE Compression Mode

There are two types of compression that are available to zip4j: DEFLATE and STORE. DEFLATE uses Deflate compression algorithm. DEFLATE is the default compression algorithm used by zip4j.

STORE denotes uncompressed zip file. This method just put files in a zip file without any compression. This example demonstrates using STORE compression mode.

View code with code highlight


In the example above, "folder" and all of its content use STORE compression method whereas "img.jpg" uses the default compression method which is DEFLATE. seCompressionMethod sets the ZIP compression method. CompressionMethod is an enum class that contains compression methods.

There are three compression methods in this enum. However, we can only use two because "AES_INTERNAL_ONLY" is for internal use only.

Create a Password Protected Zip File

We can also create a password protected zip file using zip4j library. EncryptionMethod is an enum class that contains encryption methods. There are three encryption methods that we can use. In this example I'm gonna use AES encryption method. This example demonstrates creating a password protected zip file.

View code with code highlight


ZipFile(String zipFile, char[] password) Creates a new ZipFile instance with the zip file at the location specified in zipFile parameter. password parameter is the password of our zip file.

setEncryptFiles(boolean encryptFiles) Set the flag indicating that files are to be encrypted. We need to invoke this method in order to enable/disable zip encryption. Once the zip encryption is enabled, we add an encryption method. setEncryptionMethod(EncryptionMethod encryptionMethod) sets the encryption method used to encrypt files.

setAesKeyStrength(AesKeyStrength aesKeyStrength) sets the key strength of the AES encryption key. AesKeyStrength is an enum class that contains AES encryption key length.

There are three available key lengths that we can use. However, KEY_STRENGTH_256 is the best key length that we can use in zip4j. KEY_STRENGTH_128 is too low and KEY_STRENGTH_192 is supported only for extracting.

In the example above, "folder" is password protected inside zip file. However, "img.jpg" is not. add zp to the addFile argument-list to make "img.jpg" password protected. For example: 
...
zip.addFile(new File("img.jpg"), zp);
...
If you didn't add the ZipParameters instance with setEncryptFiles(true) and setEncryptionMethod(EncryptionMethod.AES) to one of the add*() methods that you're gonna invoke, your zip file won't be password protected.

Create a Split Zip File

To store files in split zip file we can use createSplitZipFile to split files into multiple zip files/folders and createSplitZipFileFromFolder to split a folder into multiple zip files. Take a look at this example.

View code with code highlight


If we want to split files/folders, we need to put them in a single folder and invoke createSplitZipFileFromFolder method. Take a look at this example.

View code with code highlight


Now, let's take a look at the methods' forms:

createSplitZipFile(List<File> filesToAdd, ZipParameters parameters, boolean splitArchive, long splitLength)
createSplitZipFileFromFolder(File folderToAdd, ZipParameters parameters, boolean splitArchive, long splitLength)

filesToAdd parameter is the list of files that is gonna be added to our split zip file. folderToAdd is the folder that is gonna be added to our split zip file. parameters parameter consists of parameters that will be applied to a zip file.

splitArchive parameter is a flag that enables/disables split zip file mode. splitLength parameter is the split size in bytes. Note that zip file format has a minimum split size of 65536 bytes (64KB)(1024*64=65536). An exception will be thrown if we choose a split size lower than 64KB.

If we want to create a password protected split zip file, we instantiate a ZipParamaters instance and set the necessary parameters to create a password protected zip file.

View code with code highlight


Extracting Zip File

To extract all files in a zip file, we use extractAll method. Take a look at this example.

View code with code highlight


extractAll(String destinationPath) method one parameter. destinationPath is the destination directory. extractAll method has another form:

extractAll(String destinationPath, UnzipParameters unzipParameters)

We use this form if we're dealing with symbolic links. As of this writing, UnzipParameters is not well-documented. I guess this class refers to symbolic links extraction in a zip file. To extract a single file/directory in a zip file, we use extractFile method. Take a look at this example.

View code with code highlight


extractFile(String fileName, String destinationPath) has two parameters. filename parameter refers to the path in the zip entry. When referring to a zip entry, directory separator must be forward slash("/") and path must be relative. In zip entry, a file name with "/" in the path denotes a directory.

Folder extraction using extractFile method is available to version v2.6.0 and above. destinationPath is the destination path of extracted file. Remember that the file type in destination path must be a directory/folder. Java will create destination directory if it doesn't exist.

If we want to extract a single file and give it a new name once it's extracted, we use this form of extractFile method.

extractFile(String fileName, String destinationPath, String newFileName)

For example: 
...
ZipFile zip = new ZipFile
("myzip.zip", password.toCharArray());
zip.extractFile("img.jpg", "extracted", "image.jpg");
...
fileName parameter is the path name of the file in the zip file. destinationPath parameter is the destination directory. newFileName parameter is the new name of the file in the zip file once it's extracted.

Take note that the path in fileName parameter should follow zip specification. It means that the directory separator must be "/" and the path must be relative.

If we want to stream file data in a zip entry, we can get an input stream for an entry. With this, we can read data from the input stream and write the data in an output stream. To do this, we use getInputStream(FileHeader fileHeader) method. For example, we want to get the bytes of an image.

View code with code highlight


FileHeader is a class that contains file headers of a zip entry. getFileHeader(String fileName) returns FileHeader of a zip entry if a file header with the given path equivalent to fileName parameter exists in the zip model. Otherwise, returns null.

Take note that the path in fileName parameter should follow zip specification. It means that the directory separator must be "/" and the path must be relative.

extractFile has other forms that you can check them out in the documentation.

If we want to extract a password-protected zip file, we use one of ZipFile constructors: 
ZipFile(File zipFile, char[] password)
ZipFile(String zipFile, char[] password)
Example: 
...
ZipFile zip = new ZipFile
("myzip.zip", password.toCharArray());
zip.extractAll("destination-dir");
...
Using extractFile method. 
...
ZipFile zip = 
new ZipFile
("myzip.zip", password.toCharArray());
zip.extractFile("myfile.txt", "destination-dir");
...

Rename Zip Entry

To rename a file in a zip entry, we can use renameFile(String fileNameToRename, String newFileName) method from ZipFile class.

View code with code highlight


We can use renameFile method to move an entry to another directory entry. For example: 
...
zip.renameFile("image1.jpg", "folder/image1.jpg");
...
In the example above, "image1.jpg" will be moved to "folder" directory entry. We can also move and rename file at the same time. For example: 
...
zip.renameFile("image1.jpg", "folder/moved-image1.jpg");
...
In the example above, "image1.jpg" will be moved to "folder" directory entry and will be renamed as "moved-image1.jpg". If the directory where a file is going to be moved doesn't exist, java will create one and place the file there.

If we want to rename multiple files by using renameFiles(Map<String,String> fileNamesMap) method.

View code with code highlight


A map consists of key-value pairs. In the example above, the keys are the current path name of entries and the values are the new path name of entries.

Note that zip entries can have equivalent file paths. If we rename a file in a zip file, all zip entries that have file names that are equivalent to the target file will be renamed. Also, we can rename a directory. Renaming a directory in a zip entry will update all file paths of entries in the directory.

Note that entry paths should follow zip specification. It means that the directory separator must be "/" and the path must be relative. Zip file format does not allow modifying split zip files, and Zip4j will throw an exception if an attempt is made to rename files in a split zip file.

Remove Zip Entry

If we want to remove an entry from a zip file, we can use removeFile(String fileName) method.

View code with code highlight



If we want to check if the file that we wanna remove exists in a zip file, we can get a FileHeader instance from a zip entry and check if the instance is null or not. If it's null, the file that we wanna delete doesn't exist in the zip file.

View code with code highlight


In the example above, we use another form of removeFile method which is removeFile(FileHeader fileHeader)

If we want to remove multiple files using a single method, we use removeFiles(List<String> fileNames) method. Since v2.5.0 of zip4j, we can include a directory in the fileNames list and all of its content will be removed. This example demonstrates removeFiles method.

View code with code highlight


Working with ZipInputStream and ZipOutputStream

If we want more control on how we compress/extract zip files, we can use ZipInputStream and ZipOutputStream instead of ZipFile class. ZipInputStream and ZipOutputStream in Zip4j is closely similar to ZipInputStream and ZipOutputStream in java.util.zip package.

If you're not familiar with ZipInputStream and ZipOutputStream, you should read this blogpost that I've created. The blogpost contains tutorial about java.util.zip package.

One of the differences between ZipInputStream and ZipOutputStream of java.util.zip package and Zip4j is that the zip input and output streams of Zip4j has constructors that supports password protected zip. java.util.zip package doesn't support password protected zip files. This example demonstrates creating a password-protected zip file using ZipOutputStream of Zip4j.

View code with code highlight


Next, this example demonstrates extracting password-protected zip file using ZipInputStream of Zip4j.

View code with code highlight


One of the differences between FileHeader and LocalFileHeader is that FileHeader consists of general-purpose zip headers whereas LocalFileHeader consists of headers that are local from an entry.

ProgressMonitor

If we want to monitor progress of a single action, we can use ProgressMonitor. This class can monitor the progress of some methods from ZipFile class such as addFolder, addFiles, removeFiles and extractFiles. This example demonstrates ProgressMonitor.

View code with code highlight


Take note that this is just a demonstration. That's why the result is not very pretty. We need to put more time and effort on the example above to make a pretty result. Also take note that ProgressMonitor instance from ZipFile class may not be thread-safe. Therefore, proceed with caution when you want multiple threads to access ProgressMonitor instance from ZipFile class.

Alright, let's discuss the example above. First off, we need to invoke setRunInThread(boolean runInThread) method and set its flag to true.

This enables a background thread that monitors some actions happening in ZipFile class. setRunInThread is used in conjunction with ProgressMonitor. Thus, we need to get a ProgressMonitor instance from ZipFile to manage the progress of a task in ZipFile.

To do that, we use getProgressMonitor method. This method returns a ProgressMonitor instance from a ZipFile instance.

ProgressMonitor monitors results and tasks of an action. ProgressMonitor.State has two states: BUSY and READY. READY means that ProgressMonitor is idle and ready to monitor an action. BUSY means that ProgressMonitor is already monitoring an action.

ProgressMonitor.Task contains constants that denote tasks that may occur during compression and extraction. ProgressMonitor.Result contains constants that denote the result of an operation in ZipFile class.

getPercentDone returns the progress of an action in percentage form. getFileName method from ProgressMonitor class returns the absolute path of a file being processed in our file system. getCurrentTask method returns ProgressMonitor.Task task that is currently monitored.

Some Helpful Methods of ZipFile Class

ZipFile class has some helpful methods that can come in handy.

isSplitArchive() returns true if a zip file is a split zip file. Otherwise, returns false; 
...
ZipFile zip = new ZipFile("myzip.zip");
...
System.out.println(zip.isSplitArchive());
...
getSplitZipFiles() returns a list of split zip files. 
...
ZipFile zip = new ZipFile("myzip.zip");
...
if(zip.isSplitArchive())
  List<File> splitZip = zip.getSplitZipFiles();
...
mergeSplitFiles(File outputZipFile) Merges split zip files into a single zip file without the need to extract the files in the archive. This method doesn't delete the split zip file. 
...
ZipFile zip = new ZipFile("myzip.zip");
...
if(zip.isSplitArchive())
  zip.mergeSplitFiles(new File("merged.zip"));
...
isEncrypted() Checks to see if the zip file is encrypted. 
...
ZipFile zip = new ZipFile("myzip.zip");
...
System.out.println(zip.isEncrypted());
...
isValidZipFile() Checks to see if the input zip file is a valid zip file. Note this method only checks for the validity of the headers and not the validity of each entry in the zip file. 
 ...
ZipFile zip = new ZipFile("myzip.zip");
...
System.out.println(zip.isValidZipFile());
...
setComment(String comment) Sets comment for the Zip file. Note that the zip file must exist in our file system first before we can set comments on it. 
 ...
ZipFile zip = new ZipFile("myzip.zip");
...
zip.setComment("Comment1" + "\n" + "Comment2");
...
To remove a comment, use empty string "" as argument for setComment method. getComment() returns the comment set for the Zip file.

getFileHeaders() Returns the list of file headers in the zip file. We can use file headers to list all files in every entry of a zip file. 
 ...
ZipFile zip = new ZipFile("myzip.zip");
...
List<FileHeader> fileHeaders = 
zip.getFileHeaders();
fileHeaders.stream().
forEach(fileHeader -> 
        System.out.println
        (fileHeader.getFileName()));
...
ZipParameters

ZipParameters contains parameters that define the structure of a zip file. If we instantiate ZipParameters using its default constructor. Default values of parameters are gonna be used.

These are the default values of zip parameters. 
CompressionMethod.DEFLATE
CompressionLevel.NORMAL
EncryptionMethod.NONE
AesKeyStrength.KEY_STRENGTH_256
AesVerson.Two
SymbolicLinkAction.INCLUDE_LINKED_FILE_ONLY
readHiddenFiles is true
readHiddenFolders is true
includeRootInFolder is true
writeExtendedLocalFileHeader is true
CompressionMethod.DEFLATE is the default compression method. We can change this value by calling setCompressionMethod(CompressionMethod compressionMethod). Refer to CompressionMethod class for compression method types.

CompressionLevel.NORMAL is the compression level. This parameter is only applicable to DEFLATE compression method. We can change this value by calling setCompressionLevel(CompressionLevel compressionLevel) method. Refer to CompressionLevel class for compression level types.

EncryptionMethod.NONE is the default encryption method. We change this value if we want to create a password-protected zip file. To change this value, we call setEncryptionMethod(EncryptionMethod encryptionMethod) method. Refer to EncryptionMethod class for encryption method types.

AesKeyStrength.KEY_STRENGTH_256 is the default key length of AES encryption method. To change this value, we call setAesKeyStrength(AesKeyStrength aesKeyStrength) method. Refer to AesKeyStrength for available AES key length.

AesVerson.Two is the default version of AES encryption method. To change this value, call setAesVersion(AesVersion aesVersion) method. Refer to AesVersion for AES versions.

SymbolicLinkAction.INCLUDE_LINKED_FILE_ONLY is the default action for symbolic links. To change this value, we call setSymbolicLinkAction(ZipParameters.SymbolicLinkAction symbolicLinkAction) method. Refer to ZipParameters.SymbolicLinkAction for actions for symbolic links.

readHiddenFiles parameter default value is true. To change this value, we call setReadHiddenFiles(boolean readHiddenFiles) method.

readHiddenFolders parameter default value is true. To change this value, we call setReadHiddenFolders(boolean readHiddenFolders) method.

includeRootInFolder parameter default value is true. To change this value, we call setIncludeRootFolder(boolean includeRootFolder) method. You can see the effect of this parameter if you compress a file in a directory. For example, you add this "folder/file.txt" to your zip file. If includeRootInFolder parameter is true, only "file.txt" will be included to your zip file.

writeExtendedLocalFileHeader parameter default value is true. To change this value, we call setWriteExtendedLocalFileHeader(boolean writeExtendedLocalFileHeader) method. I assume this parameter refers to extra field added to local file header. More information about extra fields can be found here.
Posted by at No comments:
Labels:

Tuesday, May 24, 2022

Java Tutorial: ResourceBundle

Chapters

Introduction

ResourceBundle enables us to pack and load locale-specific data in a persistent file. By using resource bundles, we can assign a name to our application's elements, such as GUI elements, with multiple-locale.

Also, updating locale-specific data in a resource bundle is much more easier than hardcoding it in our code. Thus, it's recommended to use resource bundles for storing names such as names of GUI elements. resource bundle has a hierarchy.

We define a base name to our base resource. Then, we can create a family of resources. For naming convention, Each bundle name in a resource bundle family, except for the base resource, should copy the name of the base resource with an abbreviation of language code. We may append country code if there's a language code in the name. We may append platform code if the country and language code are present in the name.

User underscore to separate base name and codes. For example: 
//base name
MyResources

//sibling name with language code
MyResources_en

//sibling name with language code
//and country code
MyResources_en_US

//sibling name with language code,
//country code and platform code
MyResources_en_US_UNIX
For language code reference, you may look at this article. For country code reference, you may look at this article.

Codes in the file name are case-insensitive
e.g. MyResources_en_uS
However, by convention, lowercase language code; uppercase country and platform codes are preferrable. In a list resource file name, country and platform codes should in uppercase.

Resource bundles store data in the form of case-sensitive key-value pairs. Resource bundle is categorized into two types: PropertyResourceBundle and ListResourceBundle.

PropertyResourceBundle

PropertyResourceBundle is a concrete subclass of ResourceBundle that manages resources for a locale using a set of static strings from a property file. The file extension of a property file is .properties

These are the elements that we can write to our properties file. 
# Labels
HiLabel = Hi

! Buttons
abortButton Abort
aboutButton: About
"#" and "!" denotes a comment. Characters after these symbols are ignored. Next, key-value pairs can be separated by whitespace ( ), colon (:) or equal (=) symbols.

API Note:
PropertyResourceBundle can be constructed either from an InputStream or a Reader, which represents a property file. Constructing a PropertyResourceBundle instance from an InputStream requires that the input stream be encoded in UTF-8.

By default, if a MalformedInputException or an UnmappableCharacterException occurs on reading the input stream, then the PropertyResourceBundle instance resets to the state before the exception, re-reads the input stream in ISO-8859-1, and continues reading.

If the system property java.util.PropertyResourceBundle.encoding is set to either "ISO-8859-1" or "UTF-8", the input stream is solely read in that encoding, and throws the exception if it encounters an invalid sequence.

If "ISO-8859-1" is specified, characters that cannot be represented in ISO-8859-1 encoding must be represented by Unicode Escapes as defined in section 3.3 of The Java Language Specification whereas the other constructor which takes a Reader does not have that limitation.

Other encoding values are ignored for this system property. The system property is read and evaluated when initializing this class. Changing or removing the property has no effect after the initialization.

ListResourceBundle

ListResourceBundle is an abstract subclass of ResourceBundle that manages resources for a locale in a convenient and easy to use list. File extension of this resource bundle is .java

This is how we create key-value pairs in this resource bundle. 
import java.util.ListResourceBundle;
import java.time.LocalDate;

public class ListResource extends ListResourceBundle{

  @Override
  protected Object[][] getContents(){
    return new Object[][]{
      {"item1", "Toy Car"},
      {"release-date", LocalDate.of(2021, 10, 20)},
      {"tags", new String[]{"Automotive", "Toys"}}
    };
  }
}
Remember that keys are String type and values can be of any type.

Using ResourceBundle

Now we know how to create a resource bundle. Let's try using a resource bundle in our program. First off, let's create a properties files. Create a file and name it "PropertyResources.properties" and write this in the file: 
# Labels
HiLabel: Hi

# Buttons
abortButton: Abort
aboutButton: About
We're going to create a family bundle so let's create another bundle and name it "PropertyResource_en_GB.properties" and write this in the file: 
# Labels
HiLabel = Hello

# Buttons
okButton Okay
aboutButton: About
Next, let's create a code that will access our bundle. 
import java.util.Locale;
import java.util.ResourceBundle;

public class SampleClass{

  public static void main(String[] args){
    ResourceBundle rb =
    ResourceBundle.getBundle
    ("MyResources", Locale.UK);
    //If your resource is in a package
    //("Package-Name.MyResources", Locale.UK);
    
    for(String key : rb.keySet()){
      System.out.println(key + " | " + 
      rb.getString(key));
    }
  }
}

Result
HiLabel | Hello
okButton | Okay
aboutButton | About
This code above also works with list resources which have .java file extension. Remember to compile your list resources first because java look for .class file of your list resources. In the getBundle method, we just need to put the base name of our resource bundle. We don't need to add file extensions or codes like country code.

One of the advantages of list resource to a property resource is that list resource contains values of any type whereas property resource only contain values of String type. We can use handleGetObject(String key) if we want to convert values to Object type that can be cast to other object types. handleGetObject(String key) gets an object for the given key.

handleGetObject(String key) has protected access in ResourceBundle. We need to use ListResourceBundle or PropertiesResourceBundle reference in order to access this method. For example: 
ListResourceBundle prb = 
(ListResourceBundle)ResourceBundle.getBundle
("MyResources", Locale.US);
...
prb.handleGetObject(key);
ListResourceBundle has getContents() method. This method returns an array in which each item is a pair of objects in an Object array. Resource bundles can be deployed in different ways such as deploying them together with an application. You can read them in the documentation.

When java looks up for a resource bundle, it looks for a specific bundle with specified locale. If there's no match, java will look for a bundle in the family with a locale that is equivalent to our platform's default locale which is returned by invoking Locale.getDefault.

If there's still no match, java will look for default resource bundle or base resource bundle. If there's still no match, an exception will be thrown. If a property resource and list resource have the same name and in the same package or directory, java will prioritize the list resource.

Inheritance

Resource bundle hierarchy implements inheritance. A bundle with more specific name in the family inherits key-value pairs from a bundle with less specific name. For example, Assume we have three resource bundles in the same family and the base name of the family is "MyResources": 
//base 
MyResources.properties
okButton = Ok

//specific
MyResources_en.properties
acceptButton = accept

//more specific
MyResources_en_GB.properties
confirmButton = confirm
When we use MyResources_en_GB.properties in our program, this resource bundle will inherit the values in MyResources.properties and MyResources_en.properties.

However, if the bundle with more specific name has equivalent key-value pairs to its less specific counterparts, the key-value pairs in the bundle with more specific name override the equivalent key-value pairs in the bundle with less specific name.

bundles with equivalent specificity don't inherit key-value pairs. For example: 
...
MyResources_en_US.properties
confirmButton = confirm

MyResources_en_GB.properties
commitButton = commit
When we use MyResources_en_GB.properties, it won't inherit the key-value pair in MyResources_en_US.properties. Also, list resource and property resource have different hierarchies. Thus, a list resource can't inherit any key-value pairs from property resource and vice-versa.

ResourceBundle.Control

ResourceBundle.Control defines a set of callback methods that are invoked by the ResourceBundle.getBundle factory methods during the bundle loading process.

In other words, a ResourceBundle.Control collaborates with the factory methods for loading resource bundles. The default implementation of the callback methods provides the information necessary for the factory methods to perform the default behavior.

We can override some methods of ResourceBundle.Control to change some behaviors during bundle loading process. For example, we can override getCandidateLocales method to filter candidate locales. 
import java.util.Arrays;
import java.util.List;
import java.util.Locale;
import java.util.ResourceBundle;
import java.util.ResourceBundle.Control;

public class SampleClass{

  public static void main(String[] args){
    ResourceBundle rb = 
    ResourceBundle.getBundle
    ("MyResources", Locale.FRANCE, 
     new CustomResourceControl());
     
    for(String key : rb.keySet()){
      System.out.println(key + " | " + 
      rb.getString(key));
    }
     
  }
}

class CustomResourceControl extends 
ResourceBundle.Control{
  
  @Override
  public List<Locale> 
  getCandidateLocales(String s, Locale locale) {
    if(locale.getCountry().equals("US") || 
       locale.getCountry().equals("UK")){
       return super.getCandidateLocales(s, locale);
    }
    else{
      System.err.println
      ("Warning: Locale should be US or UK.");
      System.err.println("Locale has been "
      +"automatically set to Locale.ROOT");
      return Arrays.asList(Locale.ROOT);
      System.out.println();
    }
  }
}

Result
Warning: Locale should be US or UK.
Locale has been automatically set to Locale.ROOT
Posted by at No comments:
Labels:
Subscribe to: Posts (Atom)