DEV Community: あかやん

Kotlin用のJavadoc(dokka)でドキュメント化する要素を可視性で制御する

あかやん — Wed, 18 May 2022 15:28:34 +0000

はじめに

Kotlinではソースコードのドキュメント(Javadoc)化にdokkaを使用する事が多いと思います。
dokkaは、デフォルトでprivateも含めてすべての可視性の要素がドキュメントとして出力されてしまい、ライブラリを公開した際などに不要な要素などが混じってしまう可能性があります。
その際、ドキュメント化する要素を可視性修飾子により決定することで、publicな要素のみをドキュメントとして公開できてドキュメントの可読性が向上します。その方法について紹介します。

(前提) Kotlinの可視性修飾子

https://dogwood008.github.io/kotlin-web-site-ja/docs/reference/visibility-modifiers.html
private, protected, internal, publicの4つがあります。Javaではinternalという可視性は存在しません。これは同じモジュール内から参照可能となる可視性で、ライブラリを作成するときに非常に重宝しました(Javaのpackage protectとほぼ同等かと思います)

(前提) dokkaの記述方法

build.gradle.kts

plugins {
    id("org.jetbrains.dokka") version "1.6.21"
}

apply(plugin="org.jetbrains.dokka")

buildscript {
    repositories {
        jcenter()
    }
    dependencies {
        classpath("org.jetbrains.dokka:dokka-gradle-plugin:1.6.21")
    }
}

以上を記述した上で、以下のコマンドを実行します

gradle dokkaHtml

するとbuild/dokka/配下にindex.htmlなどが作成されるかと思います。

dokkaの出力を可視性修飾子により制御する方法

build.gradle.kts

import org.jetbrains.dokka.gradle.DokkaTask

tasks.withType<DokkaTask>().configureEach {
    dokkaSourceSets {
        configureEach {
          documentedVisibilities.set(listOf(
            org.jetbrains.dokka.DokkaConfiguration.Visibility.PUBLIC,
            org.jetbrains.dokka.DokkaConfiguration.Visibility.PROTECTED
          ))
        }
    }
}

上記の例ではDokkaTaskのconfigureEachで出力する可視性として(Visibility.PUBLIC, Visibility.PROTECTED)を設定しました。
あとは、先程と同じように

gradle dokkaHtml

でpublic及びprotectedのみの要素のドキュメントを生成することが可能です。

このDokkaTaskのconfigureEach内には、他にもいろいろな項目が設定可能となっています。詳しくはこちらをご覧ください。
https://kotlin.github.io/dokka/1.6.21/user_guide/gradle/usage/

Kotlinでfatjar(shadowjar)を作る(kts版)

あかやん — Tue, 17 May 2022 06:33:49 +0000

毎回fatjarを作るときにやり方ググるのが面倒なので自分の記事としてメモしておきます。
なおGradleはkts版とします。Groovy版では少々記述を変える必要があります

参考

fatjarとは依存ライブラリも含めたjarファイルです。通常のbuildをした場合に生成されるjarファイルは依存ライブラリは含まれていなく、そのjarを実行する際には依存ライブラリを指定してあげる必要があります。
fatjarを生成しておくと、このjarファイルだけでプログラムの実行が可能となります。
なお、ここまでfatjarと書いていますが、実際に作成に使用するのはshadowjarです。

手順

新しいバージョンが常に出ているはずなので、最新のバージョンはこちらで確認しましょう
https://imperceptiblethoughts.com/shadow/getting-started/

build.gradle.kts

plugins {
    kotlin("jvm") version "1.6.20"  // ここはもともと書いてあるはず
    id("com.github.johnrengelman.shadow") version "7.1.2"
    id("java")
}

// jarファイルを実行時に実行されるメインファイルのクラスを指定する。
val jar by tasks.getting(Jar::class) {
    manifest {
        // mainメソッドが存在するファイルのパスに、末尾にKtを付与したものです。
        attributes["Main-Class"] = "packagename.XxxxxXxxxxKt"
    }
}

こうすることで、

gradle shadowJar

でbuild/libs/xxxxxxxxx-1.0-SNAPSHOT-all.jarにshadowJarが生成されます。
このjarを以下のように実行すると

java -jar build/libs/xxxxxxxxx-1.0-SNAPSHOT-all.jar

先程指定したpackagename.XxxxxXxxxxKtのmainメソッドが実行されます。

もしほかのmainメソッドを実行したい場合は

java -cp build/libs/xxxxxxxxx-1.0-SNAPSHOT-all.jar packagename.YyyyyyYyyyyyKt

のように実行することができます。この場合、build.gradle.ktsのjar manifestの記載は不要になります。(その代わりjava -jarでは実行できない)

以上です。shadowJarを使うだけであれば、pluginに2行追加するだけで良いので非常に楽です。ただ、依存の衝突などが発生した場合は大変ですがその際はMergeStrategyを記述する必要があります。

KotlinでGmailのAPI経由でメールを取得する

あかやん — Mon, 16 May 2022 11:53:14 +0000

はじめに

KotlinでGmailのメールを取得して解析したり、既読フラグを付けたりする必要があったので方法をまとめました。
流れとしては、まずGoogle Cloud Platform(GCP)上でGmailへのアクセスが可能なクライアント用OAuthトークンを発行します。
そのOAuthトークンを用いて、任意のGmailアカウントでクライアントを認証しユーザトークンを発行、そのトークンを用いてメール取得などを行います。

Google Cloud Platformでの作業

GCP上で行うことは、自分のアカウントに紐付いたGmail API用のOAuthトークンを発行することです。ここで言う「自分のアカウント」はメールを取得したいアカウントでなくてもOKです。
任意のアカウントでクライアントID用のOAuthトークンを発行し、そのトークンを用いて任意のGmailアカウント(アプリ認証済み)のメールを取得することが可能なアプリケーションを作成します。

クライアント用のOAuthトークン発行

Google Cloud Platformで、API Serviceのページに移動します。

Gmail APIを有効にします。
https://console.cloud.google.com/apis/library/gmail.googleapis.com

認証情報からOAuthトークンを発行します。

発行したトークンはこちらからjsonとしてダウンロードしておきKotlinプロジェクトディレクトリにおいておきます。

また、作成したアプリケーションは本番に公開、もしくはテストユーザとして使用したいGmailアカウントを登録しておく必要があります。

本番に公開した場合でも、credentialsが知られていなければ他人に悪用されることはありませんのでどちらでもOKだと思います。

これでGoogle Cloud Platform上での作業は終了です。

Kotlinの実装

build.gradle.ktsはこちら

dependencies {
    implementation("com.google.api-client:google-api-client:1.34.1")
    implementation("com.google.oauth-client:google-oauth-client-jetty:1.33.3")
    implementation("com.google.apis:google-api-services-gmail:v1-rev20220404-1.32.1")
}

まずはOAuth認証をする部分を実装します。

/**
   * このアプリケーションに付与する権限の一覧。必要に応じて適切に設定してください
   * https://developers.google.com/resources/api-libraries/documentation/gmail/v1/java/latest/com/google/api/services/gmail/GmailScopes.html
   */
  private val SCOPES = setOf(
    GmailScopes.GMAIL_LABELS,  // メールのラベルを取得する権限
    GmailScopes.GMAIL_READONLY,   // メールを読み取る権限
    GmailScopes.GMAIL_MODIFY,  // メールのラベルの修正や送信なども行える権限
  )

  /**
   * jsonのアプリケーション情報を用いてOAuthユーザ認証を行います。
   */
  fun getCredentials(
    httpTransport: NetHttpTransport,
    jsonFactory: GsonFactory,
    credentialsFilePath: String = "credentials.json",
    tokenDir: String = "tokens"
  ): Credential? {
    // val jsonFactory: GsonFactory = GsonFactory.getDefaultInstance()
    // Googleが提供するHTTPクライアントを生成(これは、通常のNetHttpTransportにGoogle API用のルート証明書が埋め込まれていたりするようです。)
    // val httpTransport = GoogleNetHttpTransport.newTrustedTransport()

    // OAuth認証情報の読み込み
    val inputStream = File(credentialsFilePath).inputStream()
    // json形式の認証情報を読み込む
    val clientSecrets: GoogleClientSecrets = GoogleClientSecrets
      .load(jsonFactory, InputStreamReader(inputStream))

    // 認証フローの設定をする。
    val flow: GoogleAuthorizationCodeFlow = GoogleAuthorizationCodeFlow
      .Builder(httpTransport, jsonFactory, clientSecrets, SCOPES)
      .setDataStoreFactory(FileDataStoreFactory(File(tokenDir))) // トークン保存先ディレクトリの指定
      .setAccessType("offline")  // web applicationの場合はonline, それ以外はoffline
      .build()

    // callback受け取り用URL(localhost:8888)のWebサーバを建てる
    val receiver = LocalServerReceiver.Builder().setPort(8888).build()
    // 認証用を行う(ここでWebサイトが開きユーザにアプリ認証を実行させる)
    return AuthorizationCodeInstalledApp(flow, receiver).authorize("user")
  }

getCredentials()を実行すると、以下のようなアプリケーション認証画面が立ち上がり、適切な権限を許可してアプリケーションにコールバック(localhost:8888)してあげます。

アプリケーションは受け取ったコールバックに含まれるユーザトークンをもとに、以後Gmailの操作を行っていきます。

Gmail serviceインスタンスの作成

fun main() {
  val jsonFactory: GsonFactory = GsonFactory.getDefaultInstance()
  // Googleが提供するHTTPクライアントを生成(これは、通常のNetHttpTransportにGoogle API用のルート証明書が埋め込まれていたりするようです。)
  val httpTransport = GoogleNetHttpTransport.newTrustedTransport()

  val credential = getCredentials(httpTransport, jsonFactory, "credentials.json", "tokens")
  // Gmail serviceを作成。Gmailの各種操作には以降このserviceを使用します。
  val service: Gmail = Gmail.Builder(httpTransport, jsonFactory, credential)
    .setApplicationName("kotlin-gmail-reader")
    .build()
  readMailAndRemoveUnread(service)  // 下で実装します
}

ここで作成されたserviceインスタンスを用いて以後Gmailの操作が可能となります。

そして、メールを読み込んで既読フラグを付与するプログラムを作成します。

fun readMailAndRemoveUnread(service: Gmail) {
  val user = "me"
  val targetLabel = "UNREAD" // 今回の読み込み対象のラベルは未読メールとします。INBOXやSENT,IMPORTANTなども選べます。
  val labelList = service.users().labels().list(user).execute()
  // ラベル一覧を出力してみます。
  labelList.labels.forEach(::println)
  // UNREADラベルインスタンスを取得します
  val label = labelList.labels.find { it.name == targetLabel } ?: error("$targetLabel label not found")

  // 取得対象のメッセージID一覧を取得する(ここではメールヘッダや本文は取得できない)
  val messageIdList = service.users().messages().list(user).apply {
    labelIds = listOf(label.id)
    pageToken = null  // 初回はnull。続きを取得する場合に指定する。
    includeSpamTrash = true
    maxResults = 100 // メッセージ取得数
  }.execute()

  val mailMessageList = messageIdList.messages.map { messageId ->
    // メッセージIDをもとにメッセージを取得する
    val message = service.users().messages().get(user, messageId.id).execute()

    // メール本文はBase64でエンコードされているのでデコードする
    val body = try {
      // palyloadのbodyにdata要素がある場合
      val massageBase64 = message.payload.body.getValue("data") as CharSequence
      String(BaseEncoding.base64Url().decode(massageBase64), Charset.forName("UTF-8"))
    } catch (e: Exception) {
      if (message.payload.parts.isNotEmpty()) {
        // Base64がpartsというヘッダで複数要素に分割されている場合があるのでここで結合しながらデコードする
        message.payload.parts.filter { it.body.containsKey("data") }
          .map { it.body?.getValue("data") as CharSequence }
          .map { String(BaseEncoding.base64Url().decode(it), Charset.forName("UTF-8")) }
          .joinToString("")
      } else {
        // それ以外の場合は今回は対象外とする(本来はしっかりと処理する必要があるが)
        ""
      }
    }
    // メールのヘッダがこのままでは使いにくいのでMapに変換する
    val headersMap = message.payload.headers.associate { it.name.lowercase(Locale.getDefault()) to it.value }
    // MailMessageは最下部で定義しているdata classです。
    val mailMessage = MailMessage(headersMap.getOrDefault("date", ""), headersMap.getOrDefault("from", ""), headersMap.getOrDefault("subject", ""), body)
    // メール内容を出力する
    println(mailMessage.date + " " + mailMessage.from + " " + mailMessage.subject + " " + mailMessage.body)

    // メールを既読にする(GoogleではUNREADラベルが付与されているものが未読のため、そのUNREADラベルを削除すると既読となる)
    if (message.labelIds?.contains("UNREAD") == true) {
      val batchRemoveUnreadLabel = BatchModifyMessagesRequest().apply {
        removeLabelIds = listOf(label.id)
        ids = listOf(message.id)
      }
      service.users().messages().batchModify(user, batchRemoveUnreadLabel).execute()
    }
    mailMessage
  }
}

data class MailMessage(val date: String, val from: String, val subject: String, val body: String)

以上でメールの取得やメールの既読操作などができました。
同じような操作でメールの送信なども可能になると思います。
Javaの公式ドキュメントはこちらにありますので合わせてご参照いただければと思います。
https://developers.google.com/gmail/api/quickstart/java

令和の時代にjQueryでフォームのvalidationを行う

あかやん — Wed, 11 May 2022 03:53:31 +0000

やむを得ずjQueryでフォームのvalidationを行う必要があったのでメモとして行った方法を残しておきます。

今の時代はReactやVue.jsなどの仮想DOMで簡単に行えるようになっているので、わざわざjQueryで行う必要はないのですが、どうしてもReactなどが使用できない環境でしたのでこちらの環境を使用しました。

使ったライブラリ

今回はjQuery Validation Pluginを使用しました。
思ってた１０倍は便利なライブラリでした

シンプルな使用方法

私はCDNから引っ張ってきたのでこちらを貼り付けるだけです。

<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jquery-validate/1.19.3/jquery.validate.min.js"></script>

あとは、スクリプトで対象のformにvalidate関数を仕込んであげるだけです。

<form id=validationForm>
  <input name="mail">
  ....
</form>

<script type="text/javascript">
  $(function(){
    $('#validationForm').validate({
      rules: {
        name: {
          required: true
        },
        mail: {
          required: true,
          email: true,
        },
        mailConfirm: {
          email: true,
          equalTo : "#mail"
        },
        content: {
          required: true
        },
      },
      messages: {
        name: {
          required: '名前を入力してください。',
        },
        mail: {
          required: 'メールアドレスを入力してください。',
          email: '有効なメールアドレスを入力してください。'
        },
        mailConfirm: {
          required: '確認メールアドレスを入力してください。',
          email: '有効なメールアドレスを入力してください。',
          equalTo : 'メールアドレスが一致しません。'
        },
        content: {
          required: '内容を入力してください。',
        },
      },
    });
  });
</script>

rulesではrequiredやemailなどのプリセットのルールを仕込むことができますし、正規表現でvalidationをかけることもできます(私は使っていないので割愛します)
requiredはフォームが必須の場合に使用するルールです。
emailは有効なメールアドレスのvalidationをしてくれます
equalToは指定したinput(今回は#mail)と同一の内容かをチェックしてくれます。

messagesではvalidationに失敗した場合に表示するメッセージを設定することができます。

これで最低限の機能としての実装は終わりです。
こちらで動かすと、validation失敗時にinputタグの直下にラベルが追加されるようになります。

ここで、できればエラーは赤文字にしたいと思うかもしれません。そのためのオプション機能も用意してくれています。それがerrorPlacementとsuccessです。

<script type="text/javascript">
  $(function(){
    $('#validationForm').validate({
      rules: {
        ...
      },
      messages: {
        ..
      },
    },
    errorPlacement: function (error, element) {
      // あるinputのvalidationに失敗した際に呼ばれる。自分で表示をカスタマイズしたいときに使用する。
      // error はエラー時に表示するelement(例: <label>メールアドレスを入力してください。</label>)が入っている
      // element にはエラーが発生したelement(例: <input name="mail" ...>)が入っている

      // 一例: エラー発生inputの上にあるdivのclass名を --error に変える
      const errorElement = element.closest("div")
      errorElement.removeClass()
      errorElement.addClass('xxxxxx--error')

      // 赤文字で表示できるように定義済みのクラス .item__error を使用したエレメントを errorElement の中に append する
      const errorMessage = errorElement.children("p")
      const customErrorMessage = $($.parseHTML('<span class="item__error">' + error.text() + '</span>'));
      errorMessage.append(errorMessageNodes)
    },
    success: function(error, element) {
      // あるinputのvalidationに成功したときに呼ばれる。表示済みのエラーを削除する際に使用する。
      // error はエラー時に表示していたelement(例: <label>メールアドレスを入力してください。</label>)が入っている
      // element にはエラーが発生していたelement(例: <input name="mail" ...>)が入っている

      // divに装飾していたエラー用classを戻してあげる
      const errorElement = element.closest("div")
      errorElement.removeClass()
      errorElement.addClass('xxxxxx')

      // 赤文字で表示していたエラー内容を削除する
      const errorMessage = errorElement.children("p")
      errorMessage.children(".item__error").remove()
    });
  });
</script>

以上でうまくvalidationすることができました。

Rustのシンプルなスレッドの実装

あかやん — Sun, 01 May 2022 13:41:46 +0000

一番簡単なスレッドの実装

thread::spawn(function)で実装可能。
functionには任意の関数を入れることができる。Rustでクロージャを作成するときは以下

|x, y| {}

{}の中には複数行を書くことが可能で、関数の戻り値の行のみ;無しで実装する必要がある

例

|x, y| {
  let value = x + y;
  value
}

これを踏まえてシンプルなスレッドを実装すると以下の通り。

main() {
    let mut handles = Vec::new();
    for x in 1..10 {
        handles.push(thread::spawn(move || {
            println!("{}", x)
        }));
    }
    for handle in handles {
        handle.join();  // 10スレッドの処理が終わるまで待つ
    }
}

ここで注意すべきはクロージャの前に move が書かれていること。
Rustには所有権の概念があり、それに関連したエラーです。
単にループを回してスレッドを作成するだけだと、xの所有権がthread内に移されず、スレッドが完了する前にxが寿命となる可能性があるためエラーを吐き出している。

そのため、xの所有権を各スレッドに移すためにmoveを使用している。

このようにRustでは常に所有権を意識して実装を進めなければならない。

hello world

あかやん — Sun, 01 May 2022 03:03:27 +0000

DEV Community: あかやん

Kotlin用のJavadoc(dokka)でドキュメント化する要素を可視性で制御する

はじめに

(前提) Kotlinの可視性修飾子

(前提) dokkaの記述方法

dokkaの出力を可視性修飾子により制御する方法

Kotlinでfatjar(shadowjar)を作る(kts版)

参考

手順

KotlinでGmailのAPI経由でメールを取得する

はじめに

Google Cloud Platformでの作業

クライアント用のOAuthトークン発行

Kotlinの実装

令和の時代にjQueryでフォームのvalidationを行う

使ったライブラリ

シンプルな使用方法

Rustのシンプルなスレッドの実装

一番簡単なスレッドの実装

hello world

I'm now studying Rust