binding-java/compiler/src/main/resources/org/apache/etch/bindings/java/compiler/readme.vm - etch - Git at Google

 ## Copyright 2007-2008 Cisco Systems Inc.
 ##
 ## Licensed under the Apache License, Version 2.0 (the "License"); you may not
 ## use this file except in compliance with the License. You may obtain a copy
 ## of the License at
 ##
 ##      http://www.apache.org/licenses/LICENSE-2.0
 ##
 ## Unless required by applicable law or agreed to in writing, software
 ## distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
 ## WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
 ## License for the specific language governing permissions and limitations
 ## under the License.
 // This file automatically generated by:
 //   $version
 //   $now
 // This file is automatically created and should not be edited!

 This is a description of the etch-generated files for your service.

 ----------------
 - How To Build -
 ----------------

 In the directory where the etch file is located, execute the following command:

 etch -q -d . -I . -b java -w all Blah.etch

 This would compile the service description Blah.etch, generating all java files,
 into java packages rooted in the current directory (-d .), resolving includes
 and mixins from the current directory (-I .) and being quiet about it (-q).

 Assuming the Blah.etch specified a module of "demo" and a service of Blah,
 the java files would be generated into a sub-directory demo of the current
 directory. you may now change to that directory and compile the resulting files:

 cd demo
 javac -cp %ETCH_HOME%\lib\etch-java-runtime.jar *.java

 (Assuming windows; for unix, you only need to change the slash direction and
 change %ETCH_HOME% into \$ETCH_HOME.)

 To run the service (which initially won't do anything but make a connection and
 then close it, use the following two commands in separate shells (again, from
 the demo directory):

 java -cp %ETCH_HOME%\lib\etch-java-runtime.jar;.. demo.MainBlahListener

 java -cp %ETCH_HOME%\lib\etch-java-runtime.jar;.. demo.MainBlahClient

 (Again, assuming windows; for unix, make the changes detailed above and also
 change the semi-colon in the -cp spec to a colon.)

 The first command (java ... demo.MainBlahListener) starts the service listener
 which accepts connections. The second command runs a sample client, which makes
 a connection to the running listener and then closes it again.

 Once you've compiled the service and tested the result, you may implement your
 service by adding content to the etch file, adding implementation details to the
 Impl*.java and Main*.java files, and recompiling using the above steps. You may
 also load these files into an IDE such as eclipse or intellij, or use a build
 management system such as maven or ant. Remember, whenever you change the etch
 file, you must re-etch the service description and then re-javac all the java
 files.

 -------------------
 - Generated Files -
 -------------------

 Here is a description of the generated files for a service named Blah.

 Blah.java
 BlahClient.java
 BlahServer.java

 These three files are the generated interface classes. Service defined constants
 and types are in Blah.java, as well as direction "both" messages, which are
 messages which are shared between client and server. BlahClient.java and
 BlahServer.java are respectively the messages for just the direction client or
 server. You should not edit these files.

 RemoteBlah.java
 RemoteBlahClient.java
 RemoteBlahServer.java

 RemoteBlah*.java are the generated classes which implement the interfaces,
 with message implementations which encode the message type and arguments for
 transport to the connection peer and then receive and decode any response. You
 should not edit these files.

 StubBlah.java
 StubBlahClient.java
 StubBlahServer.java

 StubBlah*.java are the generated classes which receive messages encoded by
 RemoteBlah*.java and decode them, calling the appropriate message implementation
 and then encoding and sending any result. You should not edit these files.

 ValueFactoryBlah.java

 ValueFactoryBlah.java is a generated class which contains helper code to
 serialize service defined types and also the meta data which describes the
 messages and fields, field types, timeouts, etc. You should not edit this file.

 BaseBlah.java
 BaseBlahClient.java
 BaseBlahServer.java

 BaseBlah*.java are generated classes which implement the interfaces, with
 message implementations which do nothing but throw UnsupportedOperationException.
 They can be used to supply an implementation when you don't want to immediately
 implement all the messages. You should not edit these files.

 ImplBlahClient.java
 ImplBlahServer.java

 ImplBlah*.java are the generated sample client and server implementation
 classes. They extend the generated base classes. These are used by the sample
 main programs to provide implementations of the client or server messages. Edit
 these files as you wish to implement your service (overriding the default
 implementations from the generated base classes).

 BlahHelper.java

 BlahHelper.java is a generated class which includes static methods to help
 construct transports for client and listener. You should not edit this file.

 MainBlahClient.java
 MainBlahListener.java

 MainBlah*.java are the generated sample client and server main programs.
 They show how to setup a transport and start it and how to create a session.
 Edit these files as you wish to implement your service, or just copy the code
 into your own application.
	## Copyright 2007-2008 Cisco Systems Inc.
	##
	## Licensed under the Apache License, Version 2.0 (the "License"); you may not
	## use this file except in compliance with the License. You may obtain a copy
	## of the License at
	##
	## http://www.apache.org/licenses/LICENSE-2.0
	##
	## Unless required by applicable law or agreed to in writing, software
	## distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
	## WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
	## License for the specific language governing permissions and limitations
	## under the License.
	// This file automatically generated by:
	// $version
	// $now
	// This file is automatically created and should not be edited!

	This is a description of the etch-generated files for your service.

	----------------
	- How To Build -
	----------------

	In the directory where the etch file is located, execute the following command:

	etch -q -d . -I . -b java -w all Blah.etch

	This would compile the service description Blah.etch, generating all java files,
	into java packages rooted in the current directory (-d .), resolving includes
	and mixins from the current directory (-I .) and being quiet about it (-q).

	Assuming the Blah.etch specified a module of "demo" and a service of Blah,
	the java files would be generated into a sub-directory demo of the current
	directory. you may now change to that directory and compile the resulting files:

	cd demo
	javac -cp %ETCH_HOME%\lib\etch-java-runtime.jar *.java

	(Assuming windows; for unix, you only need to change the slash direction and
	change %ETCH_HOME% into \$ETCH_HOME.)

	To run the service (which initially won't do anything but make a connection and
	then close it, use the following two commands in separate shells (again, from
	the demo directory):

	java -cp %ETCH_HOME%\lib\etch-java-runtime.jar;.. demo.MainBlahListener

	java -cp %ETCH_HOME%\lib\etch-java-runtime.jar;.. demo.MainBlahClient

	(Again, assuming windows; for unix, make the changes detailed above and also
	change the semi-colon in the -cp spec to a colon.)

	The first command (java ... demo.MainBlahListener) starts the service listener
	which accepts connections. The second command runs a sample client, which makes
	a connection to the running listener and then closes it again.

	Once you've compiled the service and tested the result, you may implement your
	service by adding content to the etch file, adding implementation details to the
	Impl.java and Main.java files, and recompiling using the above steps. You may
	also load these files into an IDE such as eclipse or intellij, or use a build
	management system such as maven or ant. Remember, whenever you change the etch
	file, you must re-etch the service description and then re-javac all the java
	files.

	-------------------
	- Generated Files -
	-------------------

	Here is a description of the generated files for a service named Blah.

	Blah.java
	BlahClient.java
	BlahServer.java

	These three files are the generated interface classes. Service defined constants
	and types are in Blah.java, as well as direction "both" messages, which are
	messages which are shared between client and server. BlahClient.java and
	BlahServer.java are respectively the messages for just the direction client or
	server. You should not edit these files.

	RemoteBlah.java
	RemoteBlahClient.java
	RemoteBlahServer.java

	RemoteBlah*.java are the generated classes which implement the interfaces,
	with message implementations which encode the message type and arguments for
	transport to the connection peer and then receive and decode any response. You
	should not edit these files.

	StubBlah.java
	StubBlahClient.java
	StubBlahServer.java

	StubBlah*.java are the generated classes which receive messages encoded by
	RemoteBlah*.java and decode them, calling the appropriate message implementation
	and then encoding and sending any result. You should not edit these files.

	ValueFactoryBlah.java

	ValueFactoryBlah.java is a generated class which contains helper code to
	serialize service defined types and also the meta data which describes the
	messages and fields, field types, timeouts, etc. You should not edit this file.

	BaseBlah.java
	BaseBlahClient.java
	BaseBlahServer.java

	BaseBlah*.java are generated classes which implement the interfaces, with
	message implementations which do nothing but throw UnsupportedOperationException.
	They can be used to supply an implementation when you don't want to immediately
	implement all the messages. You should not edit these files.

	ImplBlahClient.java
	ImplBlahServer.java

	ImplBlah*.java are the generated sample client and server implementation
	classes. They extend the generated base classes. These are used by the sample
	main programs to provide implementations of the client or server messages. Edit
	these files as you wish to implement your service (overriding the default
	implementations from the generated base classes).

	BlahHelper.java

	BlahHelper.java is a generated class which includes static methods to help
	construct transports for client and listener. You should not edit this file.

	MainBlahClient.java
	MainBlahListener.java

	MainBlah*.java are the generated sample client and server main programs.
	They show how to setup a transport and start it and how to create a session.
	Edit these files as you wish to implement your service, or just copy the code
	into your own application.