judeの最近のブログ記事

なんとなくアイデアを書いてからもう4カ月。書いたっきり手つかずで放置してたけど、突然やる気になってみた。

astah*で図を書いて redmineの wikiに埋め込むプラグインを考える その1

ソースはgithubに。例によって無保証です。
tckz's redmine_wiki_astah at master - GitHub

前のエントリに書いたように、astaファイルから図をエクスポートするのは非常に時間がかかる。だから、wikiマクロでは、エクスポート対象astaファイルをDBに記録するだけにした。そして別途cronなどを使ってエクスポート処理を動かす、という流れ。

主なfeature

• wikiマクロ、{{astah_diagram}}を追加。
• astaファイルは、public配下に置いたものまたは、リポジトリに入れたものを指定できる。

{{astah_diagram}}マクロ

    {{astah_diagram(public:foo.asta, namespace/diagram)}}
    {{astah_diagram(source:/repo/path/foo.asta, namespace/diagram)}}
    {{astah_diagram(option=value...,public:foo.asta, namespace/diagram)}}

• astaファイル：
• public:path/to/.asta
• RAILS_ROOT/public/配下に置いた.astaを指定する。
• RAILS_ROOT/public/sample.astaなら、指定する値はpublic:sample.asta
  
• source:repo/path/to/.asta
• リポジトリに格納したastaを指定する。プロジェクトにリポジトリがないと意味がない。
• wikiのsourceリンク展開と同じように記述。
• リポジトリの直下にあるsample.astaなら、source:sample.asta
  
• 図のpath：
• Asta*で図をエクスポートした際のpathに準ずる。
• 図や名前空間に「/」が含まれると、エクスポートの際に「_」に変換される。ので、マクロに指定する値も「_」に変換した値とする。他にもあるかもしれないが不明。
  

オプション：

• align=value
• 埋め込まれた図のIMG要素に追加するalign属性
• 例：right, left

• width=value
• 埋め込まれた図のIMG要素に追加するwidth属性
• 例：100px, 100%
  

• height=value
• 埋め込まれた図のIMG要素に追加するheight属性
• 例：100px, 100%

• target={_blank|any}
• 埋め込まれた図のIMG要素に追加するtarget属性
• 別ウィンドウで開くなら_blank

インストール

事前に、astah（のGUI）を実行可能な状態に。↓のエントリで書いたように、図のエクスポートにはGUIが動くように、DISPLAYとライセンスを適切に設定する必要がある。
astah*で図を書いて redmineの wikiに埋め込むプラグインを考える その1

1. プラグインをRAILS_ROOT/vendor/plugins/配下に置く。
例
    #{RAILS_ROOT}/vendor/
      plugins/
        redmine_wiki_astah/
2. redmine_wiki_astah/run-astah.shを環境に合わせて編集する。
    ASTAH_HOME : Astah*を展開したディレクトリを設定。astah-pro.jarがあるディレクトリ。
    DISPLAY    : 当該環境のディスプレイをポイントする。自分ところでは前のエントリのとおり、vncserverを使っている。
3. プラグインが使うテーブルを準備。
　　rake db:migrate:plugins RAILS_ENV=production
4. Redmineを再起動
5. 管理者でredmineにログインする。
6. プラグインの設定画面で'secret key'に適当な文字列を設定する。
7. 図のエクスポートを定期的に行うようセットアップする。

図をエクスポートする

wikiに埋め込まれたastaをエクスポートして実際の図イメージを作成する。
Astah.export_diagrams()を定期的に実行する必要がある。

こんな感じで。
#{RAILS_ROOT}/script/runner Astah.export_diagrams -e production

エクスポートしたイメージをredmineを実行しているユーザから参照できるよう、実行ユーザに注意。


おわり

astaにたくさん図が含まれるとエクスポートに何分もかかってしまう。
図のID（astaファイル中の内部的なID。APIで取得できる）があらかじめわかっていれば、特定の図だけをエクスポートすることで短縮もできるが・・・・。
先のエントリに書いたように、大き目の図が多いせいでwikiに埋め込むと小さい。widthを付けることで収まりはよくなるが、リンクをクリックして図だけを表示しないと読み取るのは難しいかも。

環境：
  CentOS 5.5 i386
    ruby-1.8.7-p299(from source)
      redmine-1.0.0
      sqlite3-ruby (1.3.1)
    sqlite-3.7.0-1
    astah* pro 6.2

受託開発の見積りをすることがある。

このフェーズにおいてもJUDEを利用しています。
以前はモデリングはともかく数字の部分が「KKD（経験・勘・度胸）」だったのだけど、ここ二年ぐらいはファンクションポイントによる見積りにチャレンジしているのです。
※機能規模と関連の薄い部分（導入とか利用者トレーニングとかバッファ）は相変わらずKKDだけど。

• ヒアリングしたメモをマインドマップにざらーっと書き出しつつ、思いついたことをちょいちょい書き足す
• マインドマップを見返しながらアクターとユースケースを並べる
• ざーっとエンティティを見出す
• CRUDを埋める
• FP計数
  

という感じで。

かなり詳細にシステム像をイメージしないと数字が出せないのが難点といえば難点だけど、どんなものを作るかわからないのに見積り数字が出るってのも変といえば変。
それに計数を重ね記録することで、（組織/チームとしての）生産性が見えることがわかったのは収穫だったと思う。

で、

せっかくJUDEでモデリングしているのだから、これを活かしてFP計数が出来ればなお効率もいいだろう、という話し。
すでにやっておられる方がいるので今更感はあったのだけど、これも理解を深めるため&自分都合の使い易さのためということで。

judeユーティリティ

■実行環境
 OS: CentOS 5.2 i386
   libxml2: 2.6.26-2.1.2.6
   ruby: 1.8.5-5.el5_2.3
     rubygems: 1.2.0
     libxml-ruby: 0.8.3 (gem)
   JRE: Sun Java 1.6.0_07
     jruby: 1.1.4
     JUDE-Pro: 5.4

※注意：プログラムの実行結果について作者はなんら責任を持ちませんので悪しからず。

このFP計数ユーティリティにおける前提条件は以下のとおり。

• データファンクション（以下DF）：
• JUDEモデルでいうと以下のいずれかで、属性が1つ以上あるものをDFとみなす。
  　<<entity>>なclass
  　ERエンティティ
  
• DFのファイルタイプ（ILF/EIF）：
• CRUD図で当該エンティティに対する操作の有無で判断、または手動付与
  　Rのみのエンティティ→EIF扱い
  　CUDのいずれかが設定されているエンティティ→ILF扱い
  
• DFのDET：
• 非PKな属性の数をDETとみなす
• 「JUDE APIを jrubyから使う その1 」で書いたようにIdentifierを使ったモデリングをするようにしているので、主キーにはユーザ識別可能なデータは出てこない、とみなしています
  
• DFのRET：
• 考えられるグループを@retアノテーションで列挙する。列挙された@retアノテーションの数をRETとする。
• ここでのアノテーションとはjavaのアレではなく、JUDEにタグ付き値がなかったころに独自データを付与するため作ったオレオレ表記。
  モデルの定義中の「@アノテーション名（空白）値」という記述部分を抜き出してデータとします。
• とあるエンティティが「xxx種別」の値で意味合いを制御するようなモデリングの場合に、
  　@ret xxx種別が講師の場合
  　@ret xxx種別が講師以外の場合
  のようにエンティティの定義に記述することでRET=2と計数します
  
• トランザクショナルファンクション（以下TF）は、JUDEモデルでいうとユースケース1つに対応するものとします。
• TFのファイルタイプ（EI/EO/EQ）：
• TFのCRUD操作から判断させるか手動で付与します
• RのみのTF→EO
  CUDあり→EI
  
• ユースケースに対して@tfアノテーションで明示指定
  　@tf eo
  　@tf ei
  　@tf eq
• 結果的にCRUDからはEQが出てこないのだけども、全く加工のない操作って少ないのではないかと考えたから
  
• TFのFTR：
• 当該ユースケースのCRUDで操作対象となっているエンティティの個数をFTRとします
  
• TFのDET：
• ここはまだ方式を確立しかねている
• 現状は、当該TF（ユースケース）の直下に「FP-」で始まる名前のシーケンス図を書き、アクターが発するメッセージから計数することにしています
  例：「FP-社員情報を登録する」みたいな感じで。
  
• DET＝メッセージ（=トリガ）＋操作の引数の個数＋返り値の個数
• 「操作」に対して返り値は1つしか指定できないので、返り値にclassを指定した場合はその属性の数を返り値の個数とします
• あるいは、返り値ではなく「操作」の「out」パラメータとして記述します
  

FP計数周辺に絞った手順

1. モデリング

• ユースケースをモデリング
• TFのDET計数用シーケンス図作成
  
• ERモデリング（クラス図でもよい）
• CRUD表作成してユースケースとエンティティの操作を結びつける

2. 計数元ネタファイル作成

• judeファイルからAPIを使ってFP計数に必要な情報を抽出→中間XMLファイル
  ※linuxの操作例

  % env CLASSPATH=./jude-pro.jar jruby ./jude_export.rb -o 出力中間.xml 入力.jude
  

  
  
• 中間XMLファイルからFP計数→TSVファイルに出力
  ※linuxの操作例

  % ./calc_fp.rb -e cp932 -o 出力.txt 入力中間.xml
  

  
  
• TSVファイルを雛形xlsに貼り付けて集計
• TSVファイルをテキストエディタで開いてコピー&ペースト
• アーカイブにFP-hinagata.xlsというxlsブックが入っています。TSV全体をコピペで[ファンクション]シートに貼り付けます
• もし既存の表をはみ出たら適宜書式をコピーしておきます
  

3. FP計数

• 一般システム特性記入
• [一般システム特性]シートに数字を入れます
• この辺が参考になります
  
• 雛形xlsのピボットテーブル更新
• [業務単位FP集計]シート
• [FP概算法]シート
• [FP試算法]シート
• FP概算法、FP試算法についてはこの辺を参考にしました。
• 個人的な感覚では試算法だと数字が離れるなーという印象。rapidに見積もる必要がある、あるいは画面項目を想定するほど情報が揃っていないときは概算法のほうがいいなという感触。
  

ファンクションポイント法自体については「失敗のないファンクションポイント法 」という本を参考にしています。
この本は項目説明が網羅されているだけでなく例示が勉強になります。300ページちょいの本ですが、約200ページを「計測実習」に割いており非常に具体的で参考になります。

JUDE 5.3には編集APIのサンプルとしてDBリバースのプログラムが付属しています。
サンプルといっても十分便利。DB接続可能なときはこれを利用している。


何かしらのシステムやアプリを引き継ぐと、DDLすら提示されず、「テーブル定義書」「テーブル設計書」といった名称のxlsブックだけ出てくる場合がある。困ったことによくある。
目視でぽちぽちjudeにエントリしてもいいのだけど、編集APIのプラクティスを兼ねてインポートツールを書いた。

要するにCSVで記述したERエンティティをjudeモデルとして一括登録、というもの。
※注意：judeファイルになんらか問題が発生しても責任を負いかねます。自己責任で。そしてバックアップ or リビジョン管理重要。

judeユーティリティ

1. xlsからCSVを作成する
• 記述例はアーカイブ同梱のsamp1.xlsを参照
• 「テーブル定義書」のレイアウトは様々。それに合わせて以下のようなCSVファイルを出力するようマクロを調整のこと
• 1CSVファイル＝1エンティティ
• 1行＝1属性
• CSVファイル内の最初の列が「#」で始まる行はメタ情報行
• #@entity行
• 1列目：エンティティの論理名
• 2列目：エンティティの物理名
• 次に#で始まる行は各列の値の意味を指定するヘッダ。認識するヘッダは以下の通り
  

  logicalname	属性の論理名
  physicalname	属性の物理名
  domain	属性のドメイン（の論理名） 更新対象judeファイル内に同名の論理名を持つドメインがない場合は作成される
  type	属性のデータ型 更新対象judeファイル内に同名のデータ型がない場合は作成される
  length	属性の長さ
  nn	NOT NULLかどうか 非空文字ならNOT NULL指定
  default	属性のデフォルト値
  pk	PRIMARY KEY制約をつけるかどうか 非空文字ならPRIMARY KEY指定

• excelがインストールされたwindows上で同梱のmake_csv.jsマクロ実行し、全シートをCSV出力します
• 出力ファイル名は"シート名.csv"になります。
  シートごとに別ファイルに出力されます
  

  
  > cscript.exe make_csv.js samp1.xls
  
  

• 編集APIの仕様で以下の点に注意
• 論理名のないエンティティは登録できない
• 論理名のない属性は登録できない
• 同じ論理名を持つエンティティが既に存在すると登録できない
• データ型に英小文字を指定しても英大文字になる
• GUIでは英小文字名称のデータ型を登録できるけど、編集APIでcreateすると大文字になる。
  
2. 出来たCSVをjudeファイルにインポートする
• 実行例
  

  
  $ env CLASSPATH=./jude-pro.jar jruby ./import_ermodel.rb --fs=, -o new.jude samp2.csv
  
        

  ※インポートのデフォルトのフィールド区切りは「HT」です。--fsでカンマを指定しています。
  ※jude-pro.jarがカレントにある前提
• 存在しないjudeファイルを指定してもよいし、既存のjudeファイルを指定してもよいです。
  存在しないjudeファイルを指定するとjudeファイルが作成されます。
  新規judeファイルに出力しインポート後の内容を確認して問題なさそうならマージするという手順がいいと思う。
• 本スクリプトは日本語環境で作成されたjudeファイルを前提としています。
  編集APIサンプルのように createERModel(project, "ER Model");でIERModelを作成すると、日本語環境GUIでマージできなかった。日本語環境GUIで作ったjudeファイルの場合、IERModelの名称が"ERモデル"（これはエクスポートするとわかる）となっていることに関係するのではないかと想像している。
  
  

■実行環境
 OS: CentOS 5.2 i386
   JRE: Sun Java 1.6.0_07
     jruby: 1.1.4
     JUDE-Pro: 5.3.0

モデル編集APIは、「図要素」を編集できるようになるとうれしい。図中のモデルの位置だとか大きさ。GUIの自動レイアウトがもうひとつだなぁと感じている。何かしらのレイアウトエンジンを使って独自の整列ができるようになったらかなり素敵だと思うんだけどな。

JUDEには無償のCommunity版と有償のProfessional版がある。
両者の違いは製品公式ページの機能比較表のとおり。
結構Community版使ってますみたいなエントリを見かけるんだけども、自分がPro版購入を決めたポイントを並べてみる。
※僕はチェンジビジョンの関係者ではありません。

1. EMF出力できる
   
   • 特にコピー&ペーストでWord等office文書に貼り付けられるところがいい。
   • ビットマップでなくベクターグラフィックだから、拡大縮小しても印刷しても綺麗。貼り付け先文書内で好きな大きさにできる。
2. ステレオタイプのアイコンを指定できる
   • 機能比較表ではさらっと書いてあるけど、これはかなりうれしい。
   • boundary（メロンが横になった記号）やactor（棒人間）に帳票や人を示すビットマップを指定すると「普通の人」も見る気になってくれる
     
   • オブジェクトごとにUML表記/アイコン表記を切り替えられるので、読み手に合わせた作図をしつつ、情報量はキープみたいな使い方。
3. モデルから関連する図へジャンプできる
   • これ
   • このモデルが使われているあの図はどこだっけ・・、とモデル基点で図を逆引きできるのは地味に便利。
4. CRUDマトリクスを書ける
   • ファンクションポイント法による見積りのソースに使えてうれしい
   • Com版とPro版の違い、とは関係ないが、CRUDの軸に指定したユースケース図にユースケースを足したとき、ER図にモデルを足したときに、CRUD表の当該モデルに対する行/列が自動で追加されるのは本当にうれしい機能だ。
5. 別名をつけられる
   • クラスの名前や属性の名前など、日本語表記と英語表記を付けることが出来る。
   • モデリングは日本語で行い、SQL出力など英語表記にしたい部分だけ英語、という使い分けができて助かる
6. APIの違い
   • ER図（系のモデル）、CRUDの情報を取れるのはかなりのアドバンテージ
     
7. プロジェクトをマージできる
   • judeを2つ起動して、片方のjudeからもう片方にコピー&ペースト、ということが「出来ない」ので、その代わりとして使えるから。

ちょっとした違いかもしれないけど、普段の業務でしみじみ便利だなーと思う瞬間。
こういう違いを知らずにCommunity版を使ってる人がいたらちょっともったいないな、と思ったので書いてみた。

モデリングツールにJUDEを利用している。

このツールを選んだポイントの1つはjavaを使ったAPIがあること。
5.3になって、モデル編集のAPIも追加された。

で、テーブル設計。

過去に「楽々ERDレッスン (CodeZine BOOKS) 」を読み、「Identifier」の有用さに心打たれて以来、いつもID列を設けるようにしている。

要求・要望・要件の断片からざっとエンティティを見出し、ID属性を付与、リレーションを付けて多重度を設定して・・・という手順でやっているのだけど、エンティティの数が多いと、ID属性を追加するのも結構手間。。。。

ということで、モデル編集APIを扱うプラクティスも兼ねて、JUDEプロジェクト内のERエンティティにID属性を追加するスクリプトを書いてみた。

judeユーティリティ

ちょこちょことスクリプトを書くときは、screen＋viな環境でやると調子がいい（僕は）。なので、linux上でしか確認してない。

■実行環境
 OS: CentOS 5.2 i386
   JRE: Sun Java 1.6.0_05
     jruby: 1.1.3
     JUDE-Pro: 5.3.0

■実行例

アーカイブを展開し、jude-pro.jarを展開先ディレクトリに置いてある前提。

○ERエンティティ、「ID」という論理名でSMALLINT型の属性を追加する

% env CLASSPATH=./jude-pro.jar jruby add_identifier.rb --attr-name=ID --datatype=SMALLINT judeファイルのパス

○ERエンティティに、「ID」という名前・INT型のERドメインで、「ID」という論理名の属性を追加する

% env CLASSPATH=./jude-pro.jar jruby add_identifier.rb --attr-name=ID --domain=ID judeファイルのパス

○ERエンティティに、「ID」という名前・SMALLINT型のERドメインで、「エンティティ論理名_ID」という論理名の属性を追加する

% env CLASSPATH=./jude-pro.jar jruby add_identifier.rb --attr-name=%e_ID --domain=ID --domain-datatype=SMALLINT judeファイルのパス

指定したデータ型、ドメインが存在しない場合は作成します。
作成された属性にはPK指定が付きます

■注意

• READMEにも書いてありますが無保証です
• judeファイルを書き換えますので、バックアップ必須です。ファイルが壊れても責任持てません。
• （JUDEの機能による）ロックがかかりますので、更新対象JUDEファイルをGUIで編集していない状態で実行します
• 既に主キーがついているエンティティには属性追加しません。
• 唯一の主キーが作成しようとしてる属性論理名が同じ場合はデータ型/ドメインを更新します
• 既にERモデルが作成されているJUDEファイル前提です。日本語環境以外で作成されたものがどうなるかは不明です。
  

まだベータだけど。いつリリースかなー。

CRUDの改善

• モデル軸にクラス図を選択可能にしました。

https://jude.change-vision.com/jude-web/notes/ReleaseNote-JUDE-Professional-flame.html から

自作の見積もりツールで、ユースケースとクラス図中のentityの利用関係を取得したくて、手作業でUMLモデル→ERモデル変換するという使用方法だったのだけど、これで素直にUMLモデルが使える。

JudeのERモデルにはちょっと後付け感を感じる。構造ツリー上も「別居」しているから、ユースケースとの結びつきをイメージしにくくてヤだなあと思っていたのだ。