MS Sql Server 的 SYSDATETIMEOFFSET()、SWITCHOFFSET() 和 TODATETIMEOFFSET()

在 Microsoft Sql Server 中，
datetime 資料型別是沒有時區資訊的，，
比如 2022-01-01 00:00:00 如果沒有時區資訊的話，
它可以是美國時區的 2022-01-01 00:00:00 ，也可以是台灣時區的 2022-01-01 00:00:00，
對 1970-01-01 00:00:00 UTC+0 的毫秒數間隔是不一樣的。

而 datetimeoffset 資料型別就有時區資訊，
例如 2022-01-01 00:00:00 UTC+8 就是台灣時區的 2022-01-01 00:00:00，
對應到 UTC-8 的時區 就是 2001-12-31 08:00:00 UTC-8，
只是表示方式不同，
但對 1970-01-01 00:00:00 UTC+0 的毫秒數間隔通通都是一樣的。

以下介紹我常用的三個好用 Sql Server 函式，
SYSDATETIMEOFFSET()、SWITCHOFFSET() 和 TODATETIMEOFFSET()，
可以用來對日期格式做不同處理：

SYSDATETIMEOFFSET()：
傳回擁有時區資訊的系統目前時間 (格式為 datetimeoffset(7)，即小數位數有到 7 位的有時區時間)
例如 print SYSDATETIMEOFFSET() 可印出如下結果：
2022-07-19 20:40:24.8558075 -07:00
跟 SYSDATETIME() 的差別是 SYSDATETIME() 是傳回 datetime2 格式的無時區時間，其印出結果如下：
2022-07-19 20:40:24.8558075
可以看到只差在有無包含時區資訊而已

SWITCHOFFSET(datetimeoffset_expression, timezoneoffset_expression)：
對特定有時區資訊 (沒給時區的話會被當做是 UTC+0) 的日期(datetimeoffset_expression) 用指定的時區位移(timezoneoffset_expression)
進行換算並返回相應的 dateoffset 型別結果，例如：
print SWITCHOFFSET('2022-01-01 03:00:00 +07:00', '+08:00')
的結果為：
2022-01-01 04:00:00.0000000 +08:00
可以看到 SWITCHOFFSET() 並不會改變日期的值，
也就是其日期和 1970-01-01 00:00:00 之間差距的毫秒數還是一樣，
指的還是同一個日期，只是用不同的時區格式寫出來而已。

TODATETIMEOFFSET(datetime_expression , timezoneoffset_expression)：
對特定無時區資訊 (有給時區的話會被忽略) 的日期(datetime_expression) 加上指定的時區位移(timezoneoffset_expression)
資訊，返回日期和時區組合好後的有時區資訊日期，型別為 datetimeoffset，
例如：
print TODATETIMEOFFSET('2022-01-01 03:00:00 +07:00', '+08:00')
的結果為：
2022-01-01 03:00:00.0000000 +08:00
可以看到只有時區部份的資訊被改變了，表示無時區部份的日期資訊並沒有被改變，
所以其日期和 1970-01-01 00:00:00 之間差距的毫秒數也改變了，
變成用新時區去看日期部份得到的新日期。

參考資料：

1. Transact-SQL (日期和時間資料類型和函式)
2. 使用內建函式查詢

自訂 <ol> <li> 的項目標式方式 (list-style-type 配合 @counter-style)

html 中 <ol> <li> 的項目標式方式，可以使用 css 的 list-style-type 屬性配合  @counter-style 來自訂項目顯示方式，這裡演示一個將

list-style-type : trad-chinese-informal

擴展成自己想要的項目清單顯示方式，例如此例把

一、二、三

改成：

(一)、(二)、(三)

源碼如下：

Html：

<ol class="my-custom-list-style">
  <li>1</li>
  <li>2</li>
  <li>3</li>
</ol>

CSS：

ol.my-custom-list-style {
  list-style-type: my-custom-list-style-type;
}

@counter-style my-custom-list-style-type {
  prefix: "(";
  suffix: ")";
  system: extends trad-chinese-informal;
}

成品如下：

紀錄驗證 Google 第三方登入傳入的RSA 256 JWT token 的程式碼

紀錄驗證 Google 第三方登入傳入的RSA 256 JWT token 的程式碼
, 其官方網站有公開 Public key 的 JWK，
JWK網址是：https://www.googleapis.com/oauth2/v3/certs

有兩種驗證的方法：

1. 使用第三方 JWK 驗證相關的 Library 來做驗證 (不限只能驗證 Google 的 JWK，例如也能驗證 Apple 的 JWK)。
2. 使用 Google 提供的 LIbrary 來做驗證。

首先是第一種，
1. 使用第三方 JWK 驗證相關的 Library 來做驗證 (不限只能驗證 google 的 JWT)。
範例如下：

Maven 的 pom.xml ：

<dependency>
	    <groupId>com.auth0</groupId>
	    <artifactId>java-jwt</artifactId>
	    <version>3.18.2</version>
	</dependency>
	
	<dependency>
	    <groupId>com.auth0</groupId>
	    <artifactId>jwks-rsa</artifactId>
	    <version>0.20.0</version>
	</dependency>

可能會需要 javax.xml.bind 這個 lib，因為 jdk 8 以上沒有 jaxb 模塊，詳見: 真正解决方案：java.lang.NoClassDefFoundError: javax/xml/bind/DatatypeConverter

<!-- https://mvnrepository.com/artifact/javax.xml.bind/jaxb-api -->
	<dependency>
	    <groupId>javax.xml.bind</groupId>
	    <artifactId>jaxb-api</artifactId>
	    <version>2.3.0</version>
	</dependency>

Java：

package test;

import java.io.IOException;
import java.net.URL;
import java.security.GeneralSecurityException;
import java.security.KeyFactory;
import java.security.interfaces.RSAPublicKey;
import java.security.spec.X509EncodedKeySpec;
import java.util.Base64;

import com.auth0.jwk.Jwk;
import com.auth0.jwk.JwkException;
import com.auth0.jwk.JwkProvider;
import com.auth0.jwk.UrlJwkProvider;
import com.auth0.jwt.JWT;
import com.auth0.jwt.JWTVerifier;
import com.auth0.jwt.algorithms.Algorithm;
import com.auth0.jwt.exceptions.JWTDecodeException;
import com.auth0.jwt.interfaces.DecodedJWT;

import net.sf.json.JSONObject;

public class JWTTest {
	public static void main(String[] args) throws IOException, GeneralSecurityException, JwkException {
		String token = "someGoogleJwtToken";
		
		verifyToken(token);
		
	}

	public static verifyToken(String token) {
		try {
			DecodedJWT jwt = JWT.decode(token);
			JwkProvider provider = new UrlJwkProvider(new URL("https://www.googleapis.com/oauth2/v3/certs"));
			RSAPublicKey publicKey = (RSAPublicKey) provider.get(jwt.getKeyId()).getPublicKey();
			
			Algorithm algorithm = Algorithm.RSA256(publicKey, null);
			JWTVerifier verifier = JWT.require(algorithm)
					// more validations if needed
					.build();
			jwt = verifier.verify(token);
			
			System.out.println("User Id: " + jwt.getSubject());
			System.out.println("Email: " + jwt.getClaim("email").asString());
		} catch (Exception e) {
			System.out.println("Exception in verifying " + e.toString());
		}
	}
}

再來是第二種，
2. 使用 Google 提供的 LIbrary 來做驗證。
範例如下：

Maven 的 pom.xml ：

<dependency>
		<groupId>com.google.api-client</groupId>
		<artifactId>google-api-client</artifactId>
		<version>1.32.1</version>
	</dependency>

Java：

package test;

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Collections;

import com.auth0.jwk.JwkException;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdToken.Payload;
import com.google.api.client.googleapis.auth.oauth2.GoogleIdTokenVerifier;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.json.gson.GsonFactory;

public class GoogleJWTTest2 {
	public static void main(String[] args) throws IOException, GeneralSecurityException, JwkException {
		String token = "eyJhbGciOiJSUzI1NiIsImtpZCI6ImZjYmQ3ZjQ4MWE4MjVkMTEzZTBkMDNkZDk0ZTYwYjY5ZmYxNjY1YTIiLCJ0eXAiOiJKV1QifQ.eyJpc3MiOiJodHRwczovL2FjY291bnRzLmdvb2dsZS5jb20iLCJuYmYiOjE2NTE4MzA3OTQsImF1ZCI6Ijk2MjE1NTMyNDMyMy1vY3U5MzNkazFiYzY0dGhkM3JrdnVsaXI5MHVya3Nuby5hcHBzLmdvb2dsZXVzZXJjb250ZW50LmNvbSIsInN1YiI6IjEwMjA1NTY1MzA0MDM0ODc0MzExMyIsImVtYWlsIjoiaHVnb2dvNzY0NkBnbWFpbC5jb20iLCJlbWFpbF92ZXJpZmllZCI6dHJ1ZSwiYXpwIjoiOTYyMTU1MzI0MzIzLW9jdTkzM2RrMWJjNjR0aGQzcmt2dWxpcjkwdXJrc25vLmFwcHMuZ29vZ2xldXNlcmNvbnRlbnQuY29tIiwibmFtZSI6IumDreeAmumahiIsInBpY3R1cmUiOiJodHRwczovL2xoMy5nb29nbGV1c2VyY29udGVudC5jb20vYS0vQU9oMTRHaExOWHdxT2l2cXAyOHdRY3lNZ3FGZERUU0dyYW1sSDQwTDRTejEzZz1zOTYtYyIsImdpdmVuX25hbWUiOiLngJrpmoYiLCJmYW1pbHlfbmFtZSI6IumDrSIsImlhdCI6MTY1MTgzMTA5NCwiZXhwIjoxNjUxODM0Njk0LCJqdGkiOiJmZDFlY2VmMThiNzAyZDIyNzQwNjRjZjdmMzMwOTExZDBlYzQ4NDI0In0.OFc3-NIiSsChOJWgF_SJZ9yWhSpAhY95PSllh7gSqS8YYiBJD6DIZCvbHnL2SLU69lv2kntoR-hG1aQU07ppgGN5xuqJAagvKJ8KSSkxJxSR5qOLFNMBYPghp0zgFybNEAQDTbj3E5zRlemX7w9irEMqkMliRAMDYE3aUkcOrho9X2vd9wJDrkwKmMaLfXa71MVPwIYpsOrg2Gq82nHLw24eM47VRTp3m1sqXdKz9WHgfW2_2y9GB0qn3E8Fo99wBgegRyAlz6UvbTzDNQOUdrvuSALXcrOZzog5rrfW0MinxdVfRbSNRKL0VGMJWzuGefxNqEV-Fu0CTPIqliXf1A";

		verifyToken(token);

	}

	public static boolean verifyToken(String token) {
		try {
			GoogleIdTokenVerifier verifier = new GoogleIdTokenVerifier.Builder(
					GoogleNetHttpTransport.newTrustedTransport(), new GsonFactory())
							// Specify the CLIENT_ID of the app that accesses the backend:
//							.setAudience(Collections.singletonList(
//									"962155324323-ocu933dk1bc64thd3rkvulir90urksno.apps.googleusercontent.com"))
							// Or, if multiple clients access the backend:
							// .setAudience(Arrays.asList(CLIENT_ID_1, CLIENT_ID_2, CLIENT_ID_3))
							.build();

			// (Receive idTokenString by HTTPS POST)
			GoogleIdToken idToken = verifier.verify(token);
			if (idToken != null) {
				Payload payload = idToken.getPayload();
				// Print user identifier
				String userId = payload.getSubject();
				System.out.println("User ID: " + userId);

				// Get profile information from payload
				String email = payload.getEmail();
				boolean emailVerified = Boolean.valueOf(payload.getEmailVerified());
				String name = (String) payload.get("name");
				String pictureUrl = (String) payload.get("picture");
				String locale = (String) payload.get("locale");
				String familyName = (String) payload.get("family_name");
				String givenName = (String) payload.get("given_name");
				System.out.println(email);
				// Use or store profile information
				// ...

			} else {
				System.out.println("Invalid ID token.");
			}

			return true;
		} catch (Exception e) {
			System.out.println("Exception in verifying " + e.toString());
			return false;
		}
	}
}

使用 RS256 簽名演算法對 JWT 做簽章 - Java

JWT (JSON Web Token) 可以用於儲存不敏感的訊息來讓 client 和 server 端做溝通，

其支援不同的簽名加密演算法，例如對稱加密的 HS256 或 非對稱加密的 RS256 等，
在這篇文章裡，我記錄了一下使用了 RS256 的 JWT 驗證過程。

RS256 結合了 RSASSA-PKCS1-v1_5 和 SHA-256，
RSASSA-PKCS1-v1_5 是一種非對稱加密演算法、
而 SHA-256 是一種雜湊演算法，參考 Digital Signature with RSASSA-PKCS1-v1_5。

RS256 跟 HS256 不同的地方是，RS256使用了非對稱加密的RSA演算法，所以擁有一對
Public Key (公鑰) 和 Private Key (私錀)，而 HS256 只有一把鑰匙。
在安全上，HS256 需要發佈方(例如提供 API 的 server 端)和驗證方(例如呼叫 API 的 client 端)都要擁有同一把錀匙，如果這把錀匙流露出去讓不法的第三方得知，
第三方將可使用這把錀匙偽造出假訊息的 JWT token 讓 server, client 端無法查覺。

跟只使用了一個密碼的 HS256 不同，RS256 使用了一對公錀與密錀，
提供 API 的 server 方可以以不公開的密錀對 JWT 做加密雜溱演算，
client 端及 server 端都可以用 server 公開出來的公錀來驗證 JWT 的合法性，能確認 JWT 確實為
server 端所發出且沒有被遭到竄改

Note:
 https://jwt.io/ 是一個提供線上 JWT token 產生、驗證範例的網站，想要做測試時還蠻好用的，其也提供了不同的簽名演算法可供選擇。

在這篇文中，我示範了：

1. 如何產生 RSA 的公錀及私錀。
2. 如何使用 RSA 的私錀進行 RS256 JWT 的簽發。
3. 如何使用 RSA 的公錀進行 RS256 JWT 的驗證。

下面直接上程式碼：

首先是有用到的 library dependency, 
pom.xml：

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 https://maven.apache.org/xsd/maven-4.0.0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>test</groupId>
  <artifactId>jwtTest</artifactId>
  <version>0.0.1-SNAPSHOT</version>
  
  <dependencies>
  	<!-- https://mvnrepository.com/artifact/javax.xml.bind/jaxb-api -->
	<dependency>
	    <groupId>javax.xml.bind</groupId>
	    <artifactId>jaxb-api</artifactId>
	    <version>2.3.0</version>
	</dependency>
	
	<!-- https://mvnrepository.com/artifact/io.jsonwebtoken/jjwt -->
	<dependency>
	    <groupId>io.jsonwebtoken</groupId>
	    <artifactId>jjwt</artifactId>
	    <version>0.9.1</version>
	</dependency>
  </dependencies>
  
</project>

JwtTest.java：

package main;

import java.io.UnsupportedEncodingException;
import java.security.KeyFactory;
import java.security.KeyPair;
import java.security.KeyPairGenerator;
import java.security.NoSuchAlgorithmException;
import java.security.PrivateKey;
import java.security.PublicKey;
import java.security.SecureRandom;
import java.security.spec.InvalidKeySpecException;
import java.security.spec.PKCS8EncodedKeySpec;
import java.security.spec.X509EncodedKeySpec;
import java.text.SimpleDateFormat;
import java.util.Base64;

import io.jsonwebtoken.Claims;
import io.jsonwebtoken.Jws;
import io.jsonwebtoken.Jwts;
import io.jsonwebtoken.SignatureAlgorithm;
import io.jsonwebtoken.impl.DefaultClaims;

public class JwtTest {

	public static void main(String[] args) throws Exception {
		KeyPair keyPair = generateRsaKeyPair();
        
		String publicKeyStr = "-----BEGIN PUBLIC KEY-----" + new String(Base64.getEncoder().encode(keyPair.getPublic().getEncoded()), "UTF-8") + "-----END PUBLIC KEY-----";
		String privateKeyStr = "-----BEGIN PRIVATE KEY-----" + new String(Base64.getEncoder().encode(keyPair.getPrivate().getEncoded()), "UTF-8") + "-----END PRIVATE KEY-----";
		
		System.out.println("Public Key: " + publicKeyStr);
		System.out.println("Private Key: " + privateKeyStr);
        
        String someProperyValue = "someName";
        SimpleDateFormat sdf = new SimpleDateFormat("yyyy-MM-dd");				
		Claims claims = new DefaultClaims();
        claims.setIssuer("issuer")
                .setSubject("test")
                .setExpiration(sdf.parse("2200-01-01"))
                .put("name", someProperyValue);
        
        String generatedRsaJwt = generateRsaJwt(claims, privateKeyStr);
		Claims parsedClaims = parseRsaJwt(generatedRsaJwt, publicKeyStr);
		System.out.println("JWT Token: " + generatedRsaJwt);
		//verify content
		System.out.println(someProperyValue.equals(parsedClaims.get("name", String.class))); //true
	}
	
	static String generateRsaJwt(Claims claims, String privateKeyStr) throws InvalidKeySpecException, UnsupportedEncodingException, NoSuchAlgorithmException {
		String generatedRsaJwt = null;
		
		privateKeyStr = privateKeyStr.replace("-----BEGIN PRIVATE KEY-----", "");
        privateKeyStr = privateKeyStr.replace("-----END PRIVATE KEY-----", "");
        privateKeyStr = privateKeyStr.replaceAll("\r\n", "");
        privateKeyStr = privateKeyStr.replaceAll("\\s+", "");
        
        PKCS8EncodedKeySpec keySpec_private = new PKCS8EncodedKeySpec(Base64.getDecoder().decode(privateKeyStr.getBytes("UTF-8")));
        KeyFactory keyFactory_private = KeyFactory.getInstance("RSA");
        PrivateKey privateKey = keyFactory_private.generatePrivate(keySpec_private);
        
		generatedRsaJwt = Jwts.builder()
        .setHeaderParam("typ", "JWT")
        .setClaims(claims)
        .signWith(SignatureAlgorithm.RS256, privateKey)               
        .compact();
		
		return generatedRsaJwt;
	}
	
	static Claims parseRsaJwt(String jwtToParse, String publicKeyStr) throws NoSuchAlgorithmException, InvalidKeySpecException, UnsupportedEncodingException {
		Claims parsedRsaJwtClaims = null;
		
		publicKeyStr = publicKeyStr.replace("-----BEGIN PUBLIC KEY-----", "");
		publicKeyStr = publicKeyStr.replace("-----END PUBLIC KEY-----", "");
		publicKeyStr = publicKeyStr.replaceAll("\r\n", "");
		publicKeyStr = publicKeyStr.replaceAll("\\s+", "");
		
		X509EncodedKeySpec keySpec_public = new X509EncodedKeySpec(Base64.getDecoder().decode(publicKeyStr.getBytes("UTF-8")));
        KeyFactory keyFactory_public = KeyFactory.getInstance("RSA");
        PublicKey publicKey_public = keyFactory_public.generatePublic(keySpec_public);
        
        Jws<Claims> jws = Jwts.parser()
        					  .setSigningKey(publicKey_public)
        					  .parseClaimsJws(jwtToParse);
        
        parsedRsaJwtClaims = jws.getBody();
		
		return parsedRsaJwtClaims;
	}
	
	static KeyPair generateRsaKeyPair() throws NoSuchAlgorithmException, UnsupportedEncodingException {
		KeyPair keyPair = null;
		
		SecureRandom secureRandom = new SecureRandom();
		secureRandom.setSeed("test".getBytes("UTF-8"));
		
		KeyPairGenerator keyPairGenerator = KeyPairGenerator.getInstance("RSA");	
		keyPairGenerator.initialize(2048, secureRandom); // secureRandom is not necessary,
														 // you can also use keyPairGenerator.initialize(2048); for random seed
														 // note: if use same seed for secureRandom, will get same public key and private key.
		keyPair = keyPairGenerator.generateKeyPair();
		
		return keyPair;
	}

}

說明：

1. generateRsaKeyPair() 會產生一對 RSA Public Key 及 Private Key，SecureRandom 並非必須，只是做個示範，要注意的是 SecureRandom 如果給予一樣的種子 (Seed) ，可能會造成每次產生出一樣的公錀及密錀 (但也有可能不會，看SecureRandom、KeyGenerator 等底層演算法而定)。
2. generateRsaJwt() 使用私錀為 JWT 做簽章，parseRsaJwt() 使用公錀對 JWT 做驗證，如果有驗證問題的話，例如有人用了另一個錯吳的私錀 (真正的私錀不可流露出去，理論上其他第三方應無法知道真正的私錀) 做假訊息的簽章，在用公錀驗證時就會出現驗證錯的訊息：

   Exception in thread "main" io.jsonwebtoken.SignatureException: JWT signature does not match locally computed signature. JWT validity cannot be asserted and should not be trusted.
   

參考資料：

1. Generating a JWT using an existing private key and RS256 algorithm
2. 常見簽名算法之SHA256withRSA
3. 在 Java 使用加密演算法（一）：產生與儲存 RSA 的金鑰（2017-07-19 調整）
4. Create jwt in java using Public key rsa
5. Digital Signature with RSASSA-PKCS1-v1_5

GitLab CICD - 使用 GitLab Runner

這裡紀錄下使用
GitLab 做 CICD (Continuous Integration/Continuous Deployment, 持續整合、持續佈置)
時的一些佈驟及事項

GitLab 使用了 Job, Gitlab-Runner 及 executor 的設計。

在 Git 專案根目錄上會需要建立一個描述 Job 的 .gitlab-ci.yml 檔案，
其中記載了 CICD 要做的事項流程即要執行的 script 語句。

Gitlab-Runner 會跟 Gitlab repository 連線、檢查有無分派 Job 、並接受 Job ， Gitlab-Runner 可能是被按裝在在 Windows 系統上、或是被按裝在 Linux 上、或甚至是在某台 server 跑起來的 Docker 中都有可能。

在 Gitlab-Runner 中，可以在其設定檔 config.toml 中設定多個 Gitlab-executor，當 Gitlab-Runner 接到需要執行的 Job 時，就會啟動相應 (例如 .gitlab-ci.yml 中擁有 tag1, tag2 的 Job 對應到有 tag1, tag2 的 Gitlab-executor) 的 Gitlab-executor。

因為 Gitlab-executor 本身需要跟 Giblab repository 連線，所以需要指定 Gitlab repository 的 SSL 憑證，例如如果專案位於 Gitlab 的 https://xxx.git/... 上，那就要取得 https://xxx.git 的憑證 (例如可以用 Chrome 瀏覽器去下載憑證)。

Gitlab-executor 是主要執行 .gitlab-ci.yml 中 Job 的 script 語句的環境，有分成幾種不同環境的 executor，
例如官方列出的 shell, docker, ssh 等等，可參考 Executors | GitLab。
當使用 shell 環境的 Gitlab-executor 時，相當於直接在 Git-Runner 安裝環境上直接執行 script，
例如如果 Git-Runner 裝在 Windows 系統上，相當於直接執行 Windows 的 command line 語句。
或是例如如果 Git-Runner 裝在 Linux 系統 (如果裝在 docker 運行的 Linux 上也是一樣) 上，則相當於直接執行 Linux bash 語句。

當使用 docker 環境的 Gitlab-executor 時，Gitlab-Runner 會在所處環境下以指定的 docker image (可在 .gitab-ci.yml 中指定，或是在 config.toml 中指定預設的 image) 啟動一個指定的 docker container (這時 Gitlab-Runner 所被安裝的環境下必須要事先安裝好 docker)，
Job 的 script 會以在這個被啟動的 docker container 下被執行。
例如如果啟動的 docker container 是含有安裝 php 的 container，那就能執行 Job script 的 php 語句。

這裡我以一個例子做示範，
情境是用 docker 啟動兩個 container，
一個運行 Gitlab-Runner，
另一個運行 Linux ubuntu 系統來模擬正式環境程式要佈署到的那台 server，
在這裡 Git project 假設是一個 Maven 專案，我想要利用 GitLab CICD 來對專案進行建構 war 檔 (mvn clean install)，並以 SSH 的方式傳送到佈署 server，並以 SSH 連線佈署 server 執行解包 (jar -xvf xxx.war)

以下開始示範：

首先先安裝 Gitlab-Runner，
詳請可參考官網 Install GitLab Runner | GitLab ，
在這邊我以用 docker 來安裝 Gitlab-Runner 示範，
docker 可以使用 gitlab/gitlab-runner:latest 這個 docker image 來安裝 Gitlab-Runner，

安裝完好後，接下來要來進行 Gitlab-executor 的設定，
詳請請參閱官網 Registering runners | GitLab，
設定主要以/etc/gitlab-runner/config.toml 設定檔來設定，
如果 Gitlab-Runner 不是用 root 身份啟動的話，檔案就會改放在登入 user 的位置，
例如 ~/.gitlab-runner/config.toml，可參考 Advanced configuration | GitLab 。
如果本來就有已設定好的 config.toml 檔的話，放在 Gitlab-Runner container 中的正確位置就可以了，基本上每次對 config.toml 檔的修改 Gitlab-Runner 都會偵測到並再次載入修改的設定，不太需要重開 Gitlab-Runner，

如果第一次沒有 config.toml 檔存在，想要一個範本的話，可以使用交互模示來進行 register Gitlab-executor，啟動 Gitlab-Runner 後，執行 container 的 gitlab-runner register 指令：
(假設 container 名稱取叫 my-gitlab-runner-container)
docker exec -it my-gitlab-runner-container gitlab-runner register

如果 Gitlab repository 是 https 的話，如之前所述需要設定憑證位置，指令要改成：
docker exec -it my-gitlab-runner-container gitlab-runner register --tls-ca-file=/path/to/tlsCaFile
請把 /path/to/tlsCaFile 改成憑證在 container 中的位置，

設定好以後就會多出 /etc/gitlab-runner/config.toml，
裡面的內容之後可以依自己需求需改
(保持可例如用 docker cp 取出後設定到 docker-compose volume 裡面做持久化之類)，
而註冊好的 Gitlab-Executor 也會在 GibLab 網站上各 Project (如果是 Project runner 的話) 的
CICD --> Runner 設定裡面，
需要注意的是，在 GitLab 網站介面中，有時也會把 Gitlab-executor 稱呼成 Runner，
其實可以把 Gitlab-executor 當成是 Gitlab-Runner 在不同環境下的 Job script 執行就可以比較好理解了。

我的模擬目錄如下：

/docker-compose.yml

/gitlab-runner/Dockerfile
/gitlab-runner/config/config.toml
/gitlab-runner/ssh/id_rsa
/gitlab-runner/ssh/id_rsa.pub
/gitlab-runner/ssl/gitLabCA.cer

/online-server/Dockerfile
/online-server/ssh/authorized_keys
/online-server/project/

這邊我就直接貼上 docker-compose 的設定：

docker-compose.yml:

version: '2'
services:
    docker-runner:
        build: ./gitlab-runner
        volumes:
            - /var/run/docker.sock:/var/run/docker.sock
            - ./gitlab-runner/ssl:/data/ssl/
            - ./gitlab-runner/config:/etc/gitlab-runner
    online-server:
        build: ./online-server
        volumes:
            - ./online-server/ssh:/root/.ssh
            - ./online-server/project:/data/project
        ports:
            - "2222:22"

先看 volumes 中的設定，

/var/run/docker.sock:/var/run/docker.sock 設定了 docker socket 的用法，
來讓 Gitlab-Runner 可以像宿主機 (host) 那樣使用 docker 去啟動一個 Gitlab-executor。

./gitlab-runner/ssl:/data/ssl/ 則是把 Gitlab repository 的 SSL 憑證放到 Gitlab-Runner container 中。

而 ./gitlab-runner/config:/etc/gitlab-runner 的 設定則是讓 Gitlab-Runner 的設定檔 config.toml 持久化，不要 container 關閉了以後修改就不見了。

在 /gitlab-runner/ssh 中的 id_rsa 和 id_rsa.pub 是用 ssh-keygen 指令產生出來的 SSH 私鑰 (private key) 和公鑰 (public key)，可以用來設定 Gitlab-Executor 在使用 SSH 連線時，不用密碼登入 (這邊其實公鑰用不到，公鑰主要是要放在被 SSH 連線的對方 server 上)，

詳細可參考：

[教學] 產生SSH Key並且透過KEY進行免密碼登入 | 辛比誌

在這裡我們沒有對 /gitlab-runner/ssh 設定 volumes 的原因是，

因為 Gitlab-Executor 在執行時會以 "gitlab-runner" 這樣的 user 身份做登入 (不是 root)，

所以 id_rsa 必須放在 /home/gitlab-runner/.ssh 資料夾之下，

並且 id_rsa 及它所在的資料夾都必須能為 "gitlab-runner" user 來存取，

所以之後我們會用 Dockerfile 的 ADD 指令把 id_rsa 加進 Gitlab-Runner container 中並設定擁有者和權限。

注意的是，把 id_rsa 放到 Gitlab-Runner container 中這件事只需對 shell 的 executor 做，

因為如果是 docker 的 executor，官方有說可以在 Gitlab 中設定變數 (Variables) 並在 Job 中完成 container 的 SSH private key 設定，可參考 SSH keys when using the Docker executor

現在讓我們來看 /gitlab-runner/Dockerfile 的內容：

/gitlab-runner/Dockerfile ：

FROM gitlab/gitlab-runner:latest

RUN mkdir /home/gitlab-runner/.ssh
ADD ["ssh", "/home/gitlab-runner/.ssh"]
RUN chown -R gitlab-runner:gitlab-runner /home/gitlab-runner/.ssh
RUN chmod -R 700 /home/gitlab-runner/.ssh

可以看到在 /gitlab-runner-Dockerfile 中，設定了要啟動的 docker image 為 gitlab/gitlab-runner，
建立了 gitlab-runner 身份的 .ssh 資料夾，
用 ADD 指定放進了 id_rsa，並且用 chown 更改了檔案擁有者、
用了 chmod 改變了檔案權限，700 代表只允設檔案擁有者有 read (讀), write (寫), execute (執行) 的權限，須注意的是不能把 id_rsa 權限設定的太大，例如 777，太大的權限在 SSH 連線時也有可能會被禁止。

在我們看 /gitlab-runner/config/config.toml 之前，
先來看一下 onlin-server 的設定，online-server 是用來模擬一個有開放 SSH 連接並已有安裝好 jdk 的線上佈署環境。 

/online-server/Dockerfile ：

FROM ubuntu:latest

RUN apt-get update
RUN apt-get install ssh -y
RUN apt-get install openjdk-11-jdk -y

# RUN echo "root:12345"|chpasswd # we don't need to set password for root because we want to use ssh-key-only-login

RUN sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin yes/g' /etc/ssh/sshd_config # let root user can login
#RUN sed -i 's/#PermitRootLogin prohibit-password/PermitRootLogin without-password/g' /etc/ssh/sshd_config # let root user can login but only use way without password, like ssh key

RUN sed -i 's/#AuthorizedKeysFile/AuthorizedKeysFile/g' /etc/ssh/sshd_config # let "authorized_keys" file can be used for ssh login
RUN mkdir ~/.ssh
RUN chmod -R 700 ~/.ssh

RUN service ssh start

EXPOSE 22

CMD ["/usr/sbin/sshd","-D"]

在 online-server 的 dockerfile 中，使用了 ubuntu 的 docker image，

並用 apt-get 安裝了 ssh 及  openjdk-11-jdk，

在這邊為了方便是先假設 Gitlab-Executor 會用 root 身份來登入 SSH，

不過在實際上為了安全，通常應會再設定一個非 root 的身份來讓其登入，

因為在這裡不用 root 用密碼登入 (會用 SSH key 登入)，所以沒設定密碼，如果要設定 root 的密碼的話，可以用以下指令，請把 12345 換成要的密碼，如果是要其他身份請把 root 換掉：

RUN echo "root:12345"|chpasswd

接著要修改 /etc/ssh/sshd_config 檔的內容，

因為這裡需要讓 root 身份登入，所以需要把內容裡的
#PermitRootLogin prohibit-password 換成
PermitRootLogin yes 或
PermitRootLogin without-password (可以登入，但不能用密碼登入)，

可以看到我們使用
sed -i
的指令來做修改。

然後
#AuthorizedKeysFile 也要把註解拿掉，換成

AuthorizedKeysFile

接著建立 .ssh 資料夾並設定權限，要注意的是

RUN mkdir ~/.ssh 

RUN chmod -R 700 ~/.ssh

只適用於讓 root 身份登入的情況，如果需要讓其他身份登入，請照類似
/gitlab-runner/Dockerfile 中的方式，為非 root 身份建立正確位置的 .ssh 資料夾、設定擁有者和權限。

最後用以下命令啟動 SSH service，往外打開 22 port，
並把 container 的生命週期綁在 "/usr/sbin/sshd" 上：

RUN service ssh start 

EXPOSE 22 

CMD ["/usr/sbin/sshd","-D"]

在來我們來看下 Gitlab-Executor 的設定，即 /gitlab-runner/config/config.toml，

/gitlab-runner/config/config.toml ：

concurrent = 1
check_interval = 0

[session_server]
  session_timeout = 1800

[[runners]]
  name = "xxx description"
  url = "https://xxx-git"
  token = "xxxxxxxxxxxxxxxxxxxx"
  tls-ca-file = "/data/ssl/gitLabCA.cer"
  executor = "docker"
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]
  [runners.docker]
    tls_verify = false
    image = "ubuntu:latest"
    privileged = false
    disable_entrypoint_overwrite = false
    oom_kill_disable = false
    disable_cache = false
    network_mode = "gitlab-cicd-test_default"
    volumes = ["/c/Users/xxx/.m2/repository:/.m2/repository"]
    shm_size = 0

[[runners]]
  name = "yyy description"
  url = "https://xxx-git/"
  token = "yyyyyyyyyyyyyyyyyyyy"
  tls-ca-file = "/data/ssl/gitLabCA.cer"
  executor = "shell"
  [runners.custom_build_dir]
  [runners.cache]
    [runners.cache.s3]
    [runners.cache.gcs]
    [runners.cache.azure]

在此例 config.toml 中，

有兩個 Gitlab-Executor 被設定，分別是環境為 docker 的 docker executor 和環境為 shell 的 shell executor，環境是用 executor 這個參數來設定，例如 executor = "docker"。

可以看到兩個 executor 都設定了 Gitlab reposotiry SSL 憑證的位置，即 "tls-ca-file" 這個參數設定。

在 docker executor 中，[runners.docker] 裡可以設定一些關於會被啟動的 executor 的 container 的設定，其中例如：

image 參數可設定預設 docker image，如果 GitLab CICD Job 設定檔 .gitlab-ci.yml 的 Job 沒有指定 docker image 的話，就會拿預設 docker image 來用。

volumes 可以設定 Gitlab-executor 的 volumes，在此例中因為我的宿主機是 Windows (我使用了 Windows 系充可以安裝的 Docker Desktop)，並且如剛才所說我們是使用了 Docker socket 而非 dind (Docker in Docker) 的方式，Gitlab-Executor 和 Gitlab-Runner 是平行的關係 (即不是在 Gitlab-Runner container 裡又開了一個 Gitlab-Executor container)，

所以 volumes 設定的宿主機是 Windows，

在這裡我設定了 Maven repository 的位置做 volumes 給 Docker-executor 用以避免每次執行 CICD 時，mvn clean install 都要再上網抓一次 library ，因為每次 CICD Job 執行完後，啟動起來的 Docker Gitlab-Executor 都會被銷毀掉，裡面的資料沒做特別設定的話也都會消失掉。

要注意的是，Windows 系統的路徑，例如 D:\\xxx 要寫成 /d/xxx，且路徑上不可有空白符號。

network_mode 可以設定 Docker Gitlab-Executor container 使用的 network_mode，
效果等同於 docker run 指令的 --network_mode 參數及 docker-compose.yml 裡的 network_mode 參數。
因為我的 docker-compose.yml 建立起來的 gitlab-runner 和 online-server 這兩個 container 所處的網路名稱為 gitlab-cicd-test_default，

為了讓不是被 docker-compose.yml 建立起來的 Gitlab-Executor container 能夠與 online-server 這個 container 溝通 (之後要用 SSH 去連)，所以我用了

network_mode = "gitlab-cicd-test_default"

把 executor container 加進 "gitlab-cicd-test_default" 網路中。

最後來看看 .gitlab-ci.yml 裡面寫了什麼，

.gitlab-ci.yml：

variables:
  MAVEN_OPTS: "-Dmaven.repo.local=/.m2/repository"

cache:
  paths:
    - .m2/repository/

stages:
  - build
  # - test
  - deploy

build-job-docker:
  stage: build
  image: maven:3.6.3-jdk-11
  script:
    - mvn clean install
  tags:
    - docker
  artifacts:
    paths:
      - target/*.war
    expire_in: 1 day
  when: manual

build-job-shell:
  stage: build
  script:
    - mvn clean install
  tags:
    - shell
  artifacts:
    paths:
      - target/*.war
    expire_in: 1 day 
  when: manual

deploy-job-docker-executor:
  stage: deploy
  before_script:
    ##
    ## Install ssh-agent if not already installed, it is required by Docker.
    ## (change apt-get to yum if you use an RPM-based image)
    ##
    - 'command -v ssh-agent >/dev/null || ( apt-get update -y && apt-get install openssh-client -y )'

    ##
    ## Run ssh-agent (inside the build environment)
    ##
    - eval $(ssh-agent -s)

    ##
    ## Add the SSH key stored in SSH_PRIVATE_KEY variable to the agent store
    ## We're using tr to fix line endings which makes ed25519 keys work
    ## without extra base64 encoding.
    ## https://gitlab.com/gitlab-examples/ssh-private-key/issues/1#note_48526556
    ##
    - echo "$SSH_PRIVATE_KEY" | tr -d '\r' | ssh-add -

    ##
    ## Create the SSH directory and give it the right permissions
    ##
    - mkdir -p ~/.ssh
    - chmod 700 ~/.ssh

    ##
    ## Optionally, if you will be using any Git commands, set the user name and
    ## and email.
    ##
    # - git config --global user.email "user@example.com"
    # - git config --global user.name "User name"
  script:
    - cd target
    - apt-get update && apt-get install ssh -y
    - scp -o StrictHostKeyChecking=no xxx.war root@online-server:/data/project
    - ssh -o StrictHostKeyChecking=no root@online-server "cd /data/project && jar -xvf /data/project/xxx.war"
  tags:
    - docker  
  when: manual

deploy-job-ssh-shell-executor:
  stage: deploy
  script:
    - cd target
    - scp xxx.war root@online-server:/data/project
    - ssh -o StrictHostKeyChecking=no root@online-server "cd /data/project && jar -xvf /data/project/xxx.war"
  tags:
    - shell  
  when: manual

說明：

1. 在這裡，我已經為注冊好的兩個 Gitlab executor 分別設定了 "docker" 和 "shell" 的 tag。
2. MAVEN_OPTS: "-Dmaven.repo.local=/.m2/repository" 是設定給 Maven 的環境變量，指定 Maven local repository 的存放位置，並利用 cache paths 的設定將期設成 cache，:

   cache:
     paths:
       - .m2/repository/
   

   這樣在一個 Gitlab CICD Pipeline中的 Job 可以共享 Maven 下載的 Library，不用每個 Job 都再下載一次，雖然效果跟 artifacts 很像，不過用途不太一樣，如果要在 Job 之間共享檔案並且希望能在 Gitlab 網頁界面上存取，例如被 CICD 建立 (build) or 佈署 (deploy) 的檔案，通常會使用 artifacts 而非 cache，詳情可參考 How cache is different from artifacts。
   需注意的是，以上的 Maven repository 設定只對 Docker Gitlab Executor 有效，代表的是被啟動的 Docker Gitlab Executor Container 的 Maven local repository 位置，
   如果是 Shell Gitlab Executor 的話， Gitlab Runner 本身所處的環境應該會已經先設定好 Maven 的相關配置才對。
3. 在這裡我只用到了 build, deploy 兩個 stage，所以 test stage 被注解掉了。
   artifacts 設定了要和其他 Job 共享的檔案位置，是對 project 根目錄的相對位置，在這裡 target/*.war 即是 Maven 的 clean install 命令產出的 war 檔位置，expire_in 可設置 artifact 檔留存在 Gitlab 上的時間，在留存期間我們都可以到 Gitlab 上下載。

     artifacts:
       paths:
         - target/*.war
       expire_in: 1 day
   

4. deploy-job-docker-executor 是一個 Docker Gitlab Executor，before_script 裡設定的語句可以在 script 語句執行之前被執行，在這邊執行的語句是參考了官方的範例：SSH keys when using the Docker executor ，把我們在 Gitlab 中設定 SSH_PRIVATE_KEY 參數設定到了 Docker Gitlab Executor Container 中的 SSH Private Key 應存放位置 (SSH_PRIVATE_KEY 的值即為 id_rsa 裡的 private key 內容)。
   
5. deploy-job-docker-executor 的 script 內容為，安裝 SSH 連線用軟體，
   進到 target 資料夾 (裡面有之前設定到 artifact 的 war 檔)，
   使用 scp 指令將 war 檔傳到要被布署的 server 上，
   再使用 ssh 指令登入布署 server，用 jar -xvf 指令去解開 war 檔完成佈署。
6. deploy-job-ssh-shell-executor 是一個 Shell Gitlab Executor，因為已經事先在其所在環境上 (即 Gitlab Runner 所安裝處的環境，此例為 Linux 環境) 設置好配置，所以只要直接執行 script 指令就好，script 指令基本跟 deploy-job-docker-executor 一樣，只差在不用再安裝 SSH 連線軟體。
   需要注意的是，如果 Gitllab Runner 是裝在 Windows 系統上的話，script 裡的語句就會是 Windows cmd 的語法，可能會與 Linux bash 語法稍有不同。
7. scp 及 ssh 指令的 -o StrictHostKeyChecking=no 參數是告訴 scp, ssh 指令使用"非交互方式" 執行，因為例如在第一次使用 scp, ssh 連線時，會有提示訊息詢問，例如：
   

   The authenticity of host 'xxx (xxx)' can't be established.
   RSA key fingerprint is yyyyyyy.
   Are you sure you want to continue connecting (yes/no)?
   

   但因為我們沒有辦法在 script 模式下用 yes 或 no 的交互模式，所以這時就可以用
   -o StrictHostKeyChecking=no
   來取消交互方式。
8. 因為我們的 Gitlab Executor 都是設定手動執行 (when: manual)，所以需要到 Gitlab 上自行啟動 CICD Pipeline ，如果一切都順利的話，應就可在被佈署 server 上 (即 online-server) 看到被解包的專案了。

參考資料：

1. Executors | GitLab
2. Install GitLab Runner | GitLab
3. Registering runners | GitLab
4. Advanced configuration | GitLab
5. [教學] 產生SSH Key並且透過KEY進行免密碼登入 | 辛比誌
6. SSH keys when using the Docker executor
7. Docker Desktop
8. How cache is different from artifacts
9. SSH keys when using the Docker executor

使用 Java 對檔案壓縮成 zip 及對 zip 檔解壓縮

這邊紀錄下使用 Java 壓縮/解壓縮 Zip 的方法，
以下先直接上程式碼：

ZipTest.java:

package main;

import java.io.File;
import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.io.IOException;
import java.io.InputStream;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.util.Arrays;
import java.util.Enumeration;
import java.util.LinkedList;
import java.util.Queue;
import java.util.zip.ZipEntry;
import java.util.zip.ZipFile;
import java.util.zip.ZipInputStream;
import java.util.zip.ZipOutputStream;

public class ZipTest {

	public static void main(String[] args) throws IOException {
		String srcFilePath_isFile = "D:\\某檔案.jpg";
		String srcFilePath_isDirectory = "D:\\某資料夾";
		String toZipPath = "D:\\壓縮檔.zip";
		String toUnzipDirPath = "D:\\壓縮檔解開後要輸出到的資料夾";

		//----- zip file -----
		zipFile_onlyForSingleFile(srcFilePath_isFile, toZipPath); //壓縮單一檔案
		zipFile_onlyForSingleFile(srcFilePath_isDirectory, toZipPath); //壓縮單一資料夾，不包括資料夾內的檔案
		zipFile_canAlsoHandleDirectory_stackVersion(srcFilePath_isDirectory, toZipPath); //壓縮檔案或資料夾，使用佇列實現
		zipFile_canAlsoHandleDirectory_recursionVersion(srcFilePath_isDirectory, toZipPath); //壓縮檔案或資料夾，使用遞迴實現
		
		//----- unzip file -----
		unzipFile_byZipFile(toZipPath, toUnzipDirPath); //解壓縮，使用 ZipFile
		unzipFile_byZipInputStream(toZipPath, toUnzipDirPath); //解壓縮，使用 ZipInputStream

		System.out.println("Done");
	}

	/******************** Zip file *****************/
	public static void zipFile_onlyForSingleFile(String srcPath, String toPath) throws IOException {
		File srcFile = new File(srcPath);

		File zipFile = new File(toPath);
		FileOutputStream fileOutputStream = new FileOutputStream(zipFile);
		ZipOutputStream zipOutputStream = new ZipOutputStream(fileOutputStream);

		ZipEntry zipEntry = new ZipEntry(srcFile.getName() + (srcFile.isDirectory() ? File.separator : ""));
		zipOutputStream.putNextEntry(zipEntry);
		if (srcFile.isFile()) {
			// only srcFile is a file (not a directory) needs to write binary content of
			// file
			FileInputStream fileInputStream = new FileInputStream(srcFile);
			zipOutputStream.write(fileInputStream.readAllBytes());
			fileInputStream.close();
		}

		zipOutputStream.close();
		fileOutputStream.close();
	}

	public static void zipFile_canAlsoHandleDirectory_stackVersion(String srcPath, String toPath) throws IOException {
		File srcFile = new File(srcPath);
		String baseFileName = srcFile.getName();
		Path baseFilePath = Paths.get(srcPath);

		File zipFile = new File(toPath);
		FileOutputStream fileOutputStream = new FileOutputStream(zipFile);
		ZipOutputStream zipOutputStream = new ZipOutputStream(fileOutputStream);

		// use Queue to implement a BFS(Breadth-First Search) way to read all files and
		// directory
		Queue<File> fileQueue = new LinkedList<File>();
		fileQueue.add(srcFile);
		while (fileQueue.size() > 0) {
			File firstFileInQueue = fileQueue.poll();
			String relativePath = baseFileName + File.separator + baseFilePath.relativize(firstFileInQueue.toPath());

			if (firstFileInQueue.isFile()) {
				// do zip for file
				FileInputStream fileInputStream = new FileInputStream(firstFileInQueue);

				ZipEntry zipEntry = new ZipEntry(relativePath);
				zipOutputStream.putNextEntry(zipEntry);
				zipOutputStream.write(fileInputStream.readAllBytes());

				fileInputStream.close();
			} else if (firstFileInQueue.isDirectory()) {
				File[] childFileList = firstFileInQueue.listFiles();
				if (childFileList != null && childFileList.length > 0) {
					// add files inside directory into queue
					fileQueue.addAll(Arrays.asList(firstFileInQueue.listFiles()));
				} else {
					// if it is an empty directory,
					// just put a zipEntry and don't need to write binary content (And of course you
					// can't get binary content from a directory.)
					// don't need to do specific thing to non-empty directory because directory will
					// appear in zip when you zip files inside the directory
					ZipEntry zipEntry = new ZipEntry(relativePath + File.separator); // you should add a File.separator
																						// to let zip know it is a
																						// directory

					zipOutputStream.putNextEntry(zipEntry);
				}
			}
		}

		zipOutputStream.close();
		fileOutputStream.close();
	}

	public static void zipFile_canAlsoHandleDirectory_recursionVersion(String srcPath, String toPath)
			throws IOException {
		File zipFile = new File(toPath);
		FileOutputStream fileOutputStream = new FileOutputStream(zipFile);
		ZipOutputStream zipOutputStream = new ZipOutputStream(fileOutputStream);

		zipFile_canAlsoHandleDirectory_recursionVersion_helper(srcPath, srcPath, toPath, zipOutputStream);

		zipOutputStream.close();
		fileOutputStream.close();
	}

	private static void zipFile_canAlsoHandleDirectory_recursionVersion_helper(String basePath, String srcPath,
			String toPath, ZipOutputStream zipOutputStream) throws IOException {
		String baseFileName = new File(basePath).getName();
		Path baseFilePath = Paths.get(basePath);

		File srcFile = new File(srcPath);
		File zipFile = new File(toPath);

		if (srcFile.isFile()) {
			// do zip for file
			String relativePath = baseFileName + File.separator + baseFilePath.relativize(srcFile.toPath());
			FileInputStream fileInputStream = new FileInputStream(srcFile);

			ZipEntry zipEntry = new ZipEntry(relativePath);
			zipOutputStream.putNextEntry(zipEntry);
			zipOutputStream.write(fileInputStream.readAllBytes());

			fileInputStream.close();
		} else if (srcFile.isDirectory()) {
			File[] childFileList = srcFile.listFiles();

			if (childFileList != null && childFileList.length > 0) {
				for (File childFile : childFileList) {
					zipFile_canAlsoHandleDirectory_recursionVersion_helper(basePath, childFile.getPath(), toPath,
							zipOutputStream);
				}

			} else {
				String relativePath = baseFileName + File.separator + baseFilePath.relativize(srcFile.toPath());

				ZipEntry zipEntry = new ZipEntry(relativePath + File.separator);
				zipOutputStream.putNextEntry(zipEntry);
			}
		}
	}
	
	/******************** Unzip file *****************/
	public static void unzipFile_byZipInputStream(String zipFilePath, String toPath) throws IOException {
		File toPathFile = new File(toPath);
		if (!toPathFile.exists()) {
			toPathFile.mkdirs();
		}
		
		FileInputStream fileInputStream = new FileInputStream(zipFilePath);
		ZipInputStream zipInputStream = new ZipInputStream(fileInputStream);
		
		ZipEntry zipEntry = zipInputStream.getNextEntry();
		while(zipEntry != null) {
			File file = new File(toPath + File.separator + zipEntry.getName());
			//check is zip Entry a file or an directory
			//don't use zipEntry.isDirectory() becuase it only use "zipEntry.getName().endsWith("/")" to check
			if (zipEntry.getName().endsWith(File.separator) || zipEntry.getName().endsWith("/")) {				
				if (!file.exists()) {
					file.mkdirs();
				}
			}else {
				if (!file.exists()) {
					if (!file.getParentFile().exists()) {
						file.getParentFile().mkdirs();
					}
					FileOutputStream fileOutputStream = new FileOutputStream(file);
					fileOutputStream.write(zipInputStream.readAllBytes());
					fileOutputStream.close();
				}
			}
			
			zipEntry = zipInputStream.getNextEntry();
		}
		
		zipInputStream.close();
		fileInputStream.close();
	}

	public static void unzipFile_byZipFile(String zipFilePath, String toPath) throws IOException {
		File toPathFile = new File(toPath);
		if (!toPathFile.exists()) {
			toPathFile.mkdirs();
		}
		
		ZipFile zipFile = new ZipFile(zipFilePath);
		Enumeration<? extends ZipEntry> zipEntryEnumeration = zipFile.entries();
		while(zipEntryEnumeration.hasMoreElements()) {
			ZipEntry zipEntry = zipEntryEnumeration.nextElement();	
			File file = new File(toPath + File.separator + zipEntry.getName());
			//check is zip Entry a file or an directory
			//don't use zipEntry.isDirectory() becuase it only use "zipEntry.getName().endsWith("/")" to check
			if (zipEntry.getName().endsWith(File.separator) || zipEntry.getName().endsWith("/")) {				
				if (!file.exists()) {
					file.mkdirs();
				}
			}else {
				if (!file.exists()) {
					if (!file.getParentFile().exists()) {
						file.getParentFile().mkdirs();
					}
					InputStream zipFileInputStream = zipFile.getInputStream(zipEntry);
					FileOutputStream fileOutputStream = new FileOutputStream(file);
					fileOutputStream.write(zipFileInputStream.readAllBytes());
					
					fileOutputStream.close();
					zipFileInputStream.close();
				}
			}		
		}
		zipFile.close();
	}
}

說明：

上述程式碼展示了壓縮及解壓縮的各種不同方法，
zipFile_onlyForSingleFile() 只是展示了基本用法，只處理單一檔案或單一資料夾，
可以注意到幾點：

1. 當處理資料夾時，只需要放入代表檔案 (或資料夾) 的 ZipEntry
   zipOutputStream.putEntry(zipEntry);
   不需要再寫入檔案的二進位資料，
   zipOutputStream.write(fileInputStream.readAllBytes());
   而如果是處理檔案時就需要再寫入檔案的二進位資料。
2. 設定 new ZipEntry(String name) 時，需要 name 的參數，
   其代表檔案或資料夾的路徑(連同名字)，路徑是相對於壓縮檔 root 位置，
   例如：
   xxx/yyy/zzz/someFile.jpg
   xxx/yyy/zzz/someDirectory/
   要注意如果是資料夾的話，要在最後面加上檔案路徑的分隔符號，例如 "/"

zipFile_canAlsoHandleDirectory_stackVersion() 和
zipFile_canAlsoHandleDirectory_recursionVersion() 展示了
如何壓縮一個內含多檔案(或資料夾)的巢狀結構 (即可能有多層資料夾 ) 資料夾的方法，
原理跟 zipFile_onlyForSingleFile() 一樣，只是對資料夾內的各層資料夾及內部檔案一個個的
去做設定 ZipEntry 的動作，
zipOutputStream.putEntry(zipEntry);
zipOutputStream.write(fileInputStream.readAllBytes());
只是遍歷檔案的實現方式不同而已，
zipFile_canAlsoHandleDirectory_stackVersion() 使用了佇列 (stack) 來實現，
zipFile_canAlsoHandleDirectory_recursionVersion() 使用了遞迴 (resurisive) 來實現。

在解壓縮的部份，展示了兩個方法：
unzipFile_byZipFile() 和
unzipFile_byZipInputStream()，
基本差異不大，只是使用的幫助 Class 不同而已，
unzipFile_byZipFile() 用了 ZipFile，而
unzipFile_byZipInputStream() 用了 ZipInputStream，
需要注意的是，
ZipEntry.isDirectory() 方法不是一個正確獲取 ZipEntry 是否為資料夾的好方法，
我們可以從源碼中可以看到如下程式碼：

public class ZipEntry implements ZipConstants, Cloneable {
..............
	public boolean isDirectory() {
        	return name.endsWith("/");
	}
..............
}

可以發現 isDirectory() 只是單純判斷了 ZipEntry 的 name 後面是否是 "/" 結尾，
但是如果如上述程式，我們在壓縮檔案時用 File.separator 來設定 ZipEntry 的檔案路徑分隔符的話，
判斷 ZipEntry 是否為資料夾就不應只是判斷結尾是否是 "/" ，而是看所在系統而有所不同 (例如 Unix 系統或 Windows 系統)，例如有可能分隔符會是 "/" 或 "\" 。

參考資料：

1. 使用java API進行zip遞迴壓縮資料夾以及解壓
2. Java IO 操作基础2---操作 ZIP 压缩文件
3. Java IO操作——掌握壓縮流的使用（ZipOutputStream、ZipFile、ZipInputStream）[java.util包中]
4. java压缩文件夹（含有空文件夹）

使用 Java 讀取 Neo4j 的查詢結果

Neo4j 是一套原生實現 (底層設計就是為了圖資料庫設計，而不是用例如一般關聯式資料庫去模擬) 圖資料庫(Graph Database) 的工具

Neo4j Community Edition 版本可以到 Neo4j 官網的下載中心 免費下載使用，
除了有啟動 Neo4j server 的功能外還提供了以網頁存取的方便介面 。

下載 Neo4j Community Edition 後，把下載下來的 zip 檔解壓縮，
進入到資料夾裡的 bin 資料夾，用命令列模式 (command line)
打上

neo4j console

指令後，可以用瀏覽器到 http://localhost:7474/browser/ 看到 UI 介面，提供各種功能，例如執行語法及可視化結果，預設登入 Database 的帳號密碼會都是 "neo4j" ，可以自行修改。

這邊紀錄下使用 Java 去讀取 Neo4j 查詢結果的方法，首先來看下需要的依賴 Maven Dependency:

<!-- https://mvnrepository.com/artifact/org.neo4j.driver/neo4j-java-driver -->
	<dependency>
	    <groupId>org.neo4j.driver</groupId>
	    <artifactId>neo4j-java-driver</artifactId>
	    <version>4.4.2</version>
	</dependency>
	
	<!-- https://mvnrepository.com/artifact/org.neo4j/neo4j-jdbc-driver -->
	<dependency>
	    <groupId>org.neo4j</groupId>
	    <artifactId>neo4j-jdbc-driver</artifactId>
	    <version>4.0.4</version>
	    <scope>runtime</scope>
	</dependency>
    
   <!-- https://mvnrepository.com/artifact/org.neo4j/neo4j -->
	<!-- neo4j embedded version -->
	<dependency>
	    <groupId>org.neo4j</groupId>
	    <artifactId>neo4j</artifactId>
	    <version>4.4.2</version>
	</dependency>
    

以上三個 neo4j 的 dependency 可以擇一使用，

可依你想要存取 neo4j 的方式來選擇，分述如下：

1. org.neo4j.driver 的 neo4j-java-driver ：
   使用 Driver 的方式來存取 neo4j ，有較接近 neo4j 原生結構的類別可操作使用，
   需要跟已開啟的 neo4j server 做連線，使用像例如
   neo4j://localhost:7687
   這樣的方式來操縱 neo4j 資料庫。
2. org.neo4j 的 neo4j-jdbc-driver ：
   使用 JDBC 的方式來存 neo4j ，
   需要跟已開啟的 neo4j server 做連線，使用像例如
   jdbc:neo4j:bolt://localhost:7687?user=xxx,password=xxx,scheme=basic
   的方式操縱 neo4j 資料庫。
   跟 neo4j-java-driver 比起來，neo4j-jdbc-driver 沒有接近 neo4j 原生結構的類別可操作使用，
   只能使用 jdbc 的 (Map) ResultSet.getObject() 方式等存取 
3. org.neo4j 的 neo4j ：
   使用 嵌入式(embedded) 的方式來存取本地端的 neo4j 資料庫檔案，
   可以直接處理本地端 neo4j 資料庫檔案 (通常為一個資料夾)，
   不需開啟 neo4j server 做連線，適合用在無 server 的環境，
   有較接近 neo4j 原生結構的類別可操作使用，
   例如可直接對整個 neo4j-community-4.4.2 資料夾及指定 Database 名稱來做存取。

接下來我們先來建立一個簡單的 neo4j 資料庫內容，

內容為一個英雄人物曾當過哪些英雄的關係圖，像是這個樣子：

Bruce Wayne -[hasBeenHero] -> Batman

Dick Grayson -[hasBeenHero] -> Batman

Dick Grayson -[hasBeenHero] -> Nightwing

Dick Grayson -[hasBeenHero] -> Robin

建構資料的語法如下

//create "Persion" nodes
MERGE (bruceWayne:Person {name: 'Bruce Wayne'})
MERGE (dickGrayson:Person {name: 'Dick Grayson'})
//create "Hero" nodes
WITH bruceWayne,
	 dickGrayson, 
	 [
	 	{name: 'Batman'},
	 	{name: 'Nightwing'},
	 	{name: 'Robin'}
	 ] AS heros
//create and set relatoinship
FOREACH (hero in heros | 
    CREATE (h:Hero) SET h = hero
    CREATE (dickGrayson)-[:hasBeenHero]->(h)
)
WITH bruceWayne
MATCH (batman:Hero{name:'Batman'})
CREATE (bruceWayne)-[:hasBeenHero]->(batman)

用視覺化來看的話資料庫結果會如下圖：

接下來我們來看看要如何用 Java 把資料庫的 Node 和 Relationship 都查出來，

以下直接上 Java 程式碼，實現了三個 method ，分別對應了上述的三種存取 neo4j Database 的方式，分別是：

queryByDriver() 對應 org.neo4j.driver 的 neo4j-java-driver

queryByJdbc() 對應 org.neo4j 的 neo4j-jdbc-driver

queryByEmbeddedMode() 對應 org.neo4j 的 neo4j

 Neo4jTest.java :

package main;

import java.io.File;
import java.nio.file.Path;
import java.nio.file.Paths;
import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import org.neo4j.dbms.api.DatabaseManagementService;
import org.neo4j.dbms.api.DatabaseManagementServiceBuilder;
import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Driver;
import org.neo4j.driver.GraphDatabase;
import org.neo4j.driver.Record;
import org.neo4j.driver.Result;
import org.neo4j.driver.Session;
import org.neo4j.driver.types.Node;
import org.neo4j.driver.types.Relationship;
import org.neo4j.graphdb.GraphDatabaseService;
import org.neo4j.graphdb.Transaction;
import org.neo4j.kernel.impl.core.NodeEntity;
import org.neo4j.kernel.impl.core.RelationshipEntity;

public class Neo4jTest {
	
	public static void main(String... args) throws Exception {
		String databaseName = "neo4j";
		String userName = "neo4j";
		String password = "neo4j";
		String neo4jServerUrl = "localhost:7687";
		Path neo4jDBHomeDirectoryPath = Paths.get(ClassLoader.getSystemResource("neo4j-community-4.4.2").toURI());
		//or if the database directory is located on other path:
		//Path neo4jDBHomeDirectoryPath = Paths.get("D:\\xxx\\yyy\\neo4j-community-4.4.2");
		
		queryByDriver("neo4j://" + neo4jServerUrl, userName, password);
		queryByJdbc(neo4jServerUrl, userName, password);
		queryByEmbeddedMode(neo4jDBHomeDirectoryPath, databaseName);
		
		System.out.println("Done");
	}
	
	public static void queryByDriver(String uri, String username, String password) {		
		
		try (Driver driver = GraphDatabase.driver(uri, AuthTokens.basic(username, password));
				Session session = driver.session();) {
			
			List<String> dataList = session.readTransaction(tx -> {
				List<String> resultList = new ArrayList<String>();
				
				Result result = tx.run("MATCH (person:Person)-[relationship:hasBeenHero]->(hero:Hero) "
									 + "RETURN * "
									 + "ORDER BY person.name, hero.name");
				
				while(result.hasNext()) {					
					Record record = result.next();
					Node person = record.get("person").asNode();
					Relationship relationship = record.get("relationship").asRelationship();
					Node hero = record.get("hero").asNode();
					
					String resultStr = person.get("name").asString() + " -" + relationship.type() + "-> " + hero.get("name").asString();
//					System.out.println(resultStr); // who -hasBeenHero-> whatHero
					resultList.add(resultStr);
				}
				
				return resultList;
			});
			
			for (String data : dataList) {
				System.out.println(data);
				/* output:
				   Bruce Wayne -hasBeenHero-> Batman
				   Dick Grayson -hasBeenHero-> Batman
				   Dick Grayson -hasBeenHero-> Nightwing
				   Dick Grayson -hasBeenHero-> Robin
				*/
			}
		}catch(Exception e) {
			e.printStackTrace();
		}
	}
	
	public static void queryByJdbc(String uri, String username, String password) {		
		try (Connection con = DriverManager.getConnection("jdbc:neo4j:bolt://" + uri + "?user=" + username + ",password=" + password +",scheme=basic");
				PreparedStatement pstmt = con.prepareStatement("MATCH (person:Person)-[relationship:hasBeenHero]->(hero:Hero) "
															 + "RETURN * "
															 + "ORDER BY person.name, hero.name");
				ResultSet rs = pstmt.executeQuery();
				){
			
			while(rs.next()) {
				Map person = (Map) rs.getObject("person");				
				Map relationship = (Map) rs.getObject("relationship");
				Map hero = (Map) rs.getObject("hero");
				String resultStr = person.get("name") + " -" + relationship.get("_type") + "-> " + hero.get("name");
				System.out.println(resultStr);
				/* output:
				   Bruce Wayne -hasBeenHero-> Batman
				   Dick Grayson -hasBeenHero-> Batman
				   Dick Grayson -hasBeenHero-> Nightwing
				   Dick Grayson -hasBeenHero-> Robin
				*/				
			}
		}catch(Exception e) {
			e.printStackTrace();
		}
	}
	
	// Don't need to start server manually, it will start server by itself.
	// Don't need username and password.
	public static void queryByEmbeddedMode(Path neo4jDBHomeDirectoryPath, String databaseName) {
		DatabaseManagementService databaseManagementService = new DatabaseManagementServiceBuilder(neo4jDBHomeDirectoryPath).build();
		GraphDatabaseService graphDatabaseService = databaseManagementService.database(databaseName);
		
		// Registers a shutdown hook for the Neo4j instance so that it
	    // shuts down nicely when the VM exits (even if you "Ctrl-C" the
	    // running application).
//	    Runtime.getRuntime().addShutdownHook( new Thread()
//	    {
//	        @Override
//	        public void run()
//	        {
//	        	databaseManagementService.shutdown();
//	        }
//	    } );
	    
	    try(Transaction tx = graphDatabaseService.beginTx();){
	    	org.neo4j.graphdb.Result result = tx.execute("MATCH (person:Person)-[relationship:hasBeenHero]->(hero:Hero) "
	    											   + "RETURN * "
	    											   + "ORDER BY person.name, hero.name");
			
			while(result.hasNext()) {				
				Map<String,Object> record = result.next();
				NodeEntity person = (NodeEntity) record.get("person");
				RelationshipEntity relationship = (RelationshipEntity) record.get("relationship");
				NodeEntity hero = (NodeEntity) record.get("hero");
				String resultStr = person.getProperty("name") + " -" + relationship.getType().name() + "-> " + hero.getProperty("name");
				System.out.println(resultStr);
				/* output:
				   Bruce Wayne -hasBeenHero-> Batman
				   Dick Grayson -hasBeenHero-> Batman
				   Dick Grayson -hasBeenHero-> Nightwing
				   Dick Grayson -hasBeenHero-> Robin
				*/
			}
	    }catch(Exception e) {
	    	e.printStackTrace();
	    }
	    
		databaseManagementService.shutdown();
	}
}

可以注意到的是，只有 queryByDriver() 和 queryByJdbc() 需要提供帳號及密碼，並且需要連接一個已經啟動的 neo4j Database server。

而 queryByEmbeddedMode() 不需帳號、密碼，也不需要一個已經啟動的 neo4j Database server，

它會直接對本地端的 neo4j Database folder 做存取，因為它會自己啟動 DB server ，

所以不要用例如上述的 neo4j console 指令啟動 server，不然可能會出現

Exception in thread "main" java.lang.RuntimeException: Error starting Neo4j database server at D:\xxx\yyy\neo4j-community-4.4.2\data\databases

的錯誤訊息。

原碼下載分享：

Neo4jTest.7z

參考資料：

1. Neo4j JDBC Driver Documentation
2. How to get Node object when using Neo4j jdbc?
3. Using Neo4j embedded in Java applications
4. A Guide to Neo4J with Java